rolldown.config.ts

/**
 * Rolldown configuration that dynamically builds the package it's been called from.
 *
 * This configuration works specifically for this monorepo's structure and workflow:
 * - Packages are organized under a common {@linkcode PACKAGES_FOLDER} directory
 * - Source files use TypeScript with `.ts` extensions
 * - Built files are output to a {@linkcode OUTPUT_DIR} directory
 * - The `publishConfig` field is used to override exports for publishing
 *
 * This config is designed for internal use within this project structure and is not intended as a general-purpose build configuration for external projects.
 *
 * @module
 */
import { access, cp, writeFile } from "node:fs/promises";
import { basename, extname, parse, relative, resolve } from "node:path";
import { cwd, exit } from "node:process";
import { defineConfig } from "rolldown";
import { dts } from "rolldown-plugin-dts";
import { glob } from "tinyglobby";

import type { Plugin } from "rolldown";
import type { PackageJson } from "type-fest";

// #region constants

/**
 * The directory to output the build into.
 */
const OUTPUT_DIR = "dist";
/**
 * Files to bundle from a package's `exports` while all other exported files get copied without processing.
 *
 * Matches `.ts` files that are not `.d.ts` declaration files. These files will be bundled.
 */
const FILES_TO_BUNDLE = /(?<!\.d)\.ts$/;

/**
 * The folder containing all the packages.
 */
const PACKAGES_FOLDER = `packages`;

// #endregion

// #region helpers

/**
 * Check if a file exists.
 */
const exists = (path: string): Promise<boolean> =>
	access(path)
		.then(() => true)
		.catch(() => false);

/**
 * Find the package root directory by traversing up from the given path until a `package.json` is found.
 *
 * @throws If the filesystem root is reached or if the {@linkcode PACKAGES_FOLDER} directory is reached.
 */
const getPackageDirectory = async (path: string): Promise<string> => {
	const resolvedPath = resolve(path);

	if (parse(resolvedPath).root === resolvedPath) {
		throw new Error("Reached fs root without finding a package.");
	}

	// stop if we've reached the packages container directory
	if (resolvedPath.endsWith(resolve("/", PACKAGES_FOLDER))) {
		throw new Error("A build has to be called from within a package.");
	}

	const nodeModulesIndex = resolvedPath.indexOf("node_modules");

	// continue search outside of `node_modules` to find the actual package root
	if (nodeModulesIndex > 0) {
		return getPackageDirectory(resolvedPath.slice(0, nodeModulesIndex));
	}

	const isPackage = await exists(resolve(resolvedPath, "package.json"));

	if (isPackage === false) {
		return getPackageDirectory(resolve(resolvedPath, ".."));
	}

	return resolvedPath;
};

/**
 * Recursively extract all file paths from the exports field in `package.json`.
 *
 * Handles string, array, and object formats, prioritizing `import` over `default` conditions.
 */
const getExports = (exports: PackageJson["exports"]): string[] => {
	if (exports == null) {
		return [];
	}

	if (typeof exports === "string") {
		return [exports];
	}

	if (Array.isArray(exports)) {
		return exports.flatMap((entry) => getExports(entry));
	}

	// prioritize "import" condition for ESM exports
	if (Reflect.has(exports, "import") && typeof exports.import === "string") {
		return [exports.import];
	}

	// fall back to "default" condition
	if (Reflect.has(exports, "default") && typeof exports.default === "string") {
		return [exports.default];
	}

	// recursively process nested export conditions
	return Object.values(exports).flatMap((entry) => getExports(entry));
};

/**
 * Split export entries into files to bundle and files to copy as-is based on the {@linkcode FILES_TO_BUNDLE} pattern.
 */
const resolveExports = (
	exports: readonly string[],
): { toBundle: string[]; toCopy: string[] } =>
	exports.reduce(
		(obj, entry) => {
			obj[FILES_TO_BUNDLE.test(entry) ? "toBundle" : "toCopy"].push(entry);

			return obj;
		},
		{ toBundle: [], toCopy: [] } as ReturnType<typeof resolveExports>,
	);

/**
 * A type representing a readonly array that can be nested to any depth, used for handling grouped file paths.
 */
type RecursiveReadonlyArray<T> = readonly (T | RecursiveReadonlyArray<T>)[];

/**
 * Copy the provided files to the {@linkcode OUTPUT_DIR} directory.
 */
const recursiveCopy = async (
	filepaths: RecursiveReadonlyArray<string>,
): Promise<void> => {
	await Promise.all(
		filepaths.map((filepath) => {
			if (typeof filepath === "string") {
				return cp(filepath, resolve(OUTPUT_DIR, filepath), {
					recursive: true,
					force: true,
				});
			}

			return recursiveCopy(filepath);
		}),
	);
};

/**
 * Converts a "source" path to point to the {@linkcode OUTPUT_DIR} directory and adjust file extensions for published packages.
 *
 * Converts source file paths to their built equivalents:
 * - `.ts` files become `.js` (or `.d.ts` for type declarations)
 * - Files matching {@linkcode FILES_TO_BUNDLE} are processed, others are kept as-is
 *
 * @param filePath - The original path from package.json
 * @param isType - Whether this is a type declaration path
 * @param packageRoot - The package's root directory
 */
const toDirPath = (filePath: string, isType: boolean, packageRoot: string) => {
	const newPath = relative(
		packageRoot,
		resolve(packageRoot, OUTPUT_DIR, filePath),
	);

	const extension = extname(newPath);

	return `./${
		FILES_TO_BUNDLE.test(filePath)
			? isType
				? newPath.replace(extension, ".d.ts")
				: extension === ".ts"
					? newPath.replace(extension, ".js")
					: newPath
			: newPath
	}`;
};

/**
 * Recursively transform the exports field to point to built files in the {@linkcode OUTPUT_DIR} directory.
 *
 * Handles all export formats (string, array, object) and preserves the structure while updating paths.
 *
 * @param exports - The exports field to transform
 * @param isType - Whether processing type declaration paths
 * @param packageRoot - The package's root directory
 */
const createPublishExports = (
	exports: PackageJson["exports"],
	isType: boolean,
	packageRoot: string,
): PackageJson["exports"] => {
	if (exports == null) {
		return exports;
	}

	if (typeof exports === "string") {
		return toDirPath(exports, isType, packageRoot);
	}

	if (Array.isArray(exports)) {
		return exports.map((entry) =>
			createPublishExports(entry, isType, packageRoot),
		) as typeof exports;
	}

	const exportsClone = structuredClone(exports);

	for (const [key, value] of Object.entries(exports)) {
		exportsClone[key] =
			// mark "types" condition entries as type declaration paths
			createPublishExports(value, key === "types", packageRoot) ?? null;
	}

	return exportsClone;
};

/**
 * Rolldown plugin that updates `package.json` with a `publishConfig` field containing corrected export paths.
 *
 * The `publishConfig.exports` field will override the original exports when the package is published,
 * pointing to the built files in the {@linkcode OUTPUT_DIR} directory instead of source files.
 *
 * @param packageContents - The parsed package.json contents
 * @param packageRoot - The package's root directory
 */
const setPackagePublishConfig = (
	packageContents: PackageJson,
	packageRoot: string,
): Plugin => ({
	name: "set-package-publish-config",
	buildEnd: async () => {
		const packageClone = structuredClone(packageContents);

		// add `publishConfig` with transformed exports for publishing
		packageClone.publishConfig = {
			exports: createPublishExports(packageClone.exports, false, packageRoot),
		};

		await writeFile(
			resolve(packageRoot, "package.json"),
			`${JSON.stringify(packageClone, null, 2)}\n`,
		);
	},
});

// #endregion

// #region config

/**
 * The package's "root" directory resolved from the directory the build has been called from.
 */
const WORKING_DIRECTORY = await getPackageDirectory(cwd());

// import `package.json` (guaranteed to exist at this point)
const { default: packageContents } = (await import(
	resolve(WORKING_DIRECTORY, "package.json"),
	{
		with: { type: "json" },
	}
)) as { default: PackageJson };

// skip building private packages
if (packageContents.private === true) {
	console.log(
		`\`${basename(WORKING_DIRECTORY)}\` is a private package, it won't get built`,
	);

	exit(0);
}

const {
	exports = {},
	dependencies = {},
	devDependencies = {},
	peerDependencies = {},
} = packageContents;

const external = Array.from(
	new Set([
		...Object.keys(dependencies),
		...Object.keys(devDependencies),
		...Object.keys(peerDependencies),
	]),
).flatMap((dependency) =>
	// match both the package name and any subpath imports (e.g., `lodash` and `lodash/*`)
	[dependency, new RegExp(`${dependency}/.*?`)],
);

const { toBundle, toCopy } = resolveExports(getExports(exports));

// copy all files that don't need bundling to the output folder
await recursiveCopy(
	await Promise.all(
		toCopy.map(async (entry) => glob(entry, { cwd: WORKING_DIRECTORY })),
	),
);

export default defineConfig({
	platform: "browser",
	plugins: [dts(), setPackagePublishConfig(packageContents, WORKING_DIRECTORY)],
	external,
	input: Object.fromEntries(
		toBundle.map((entry) => [
			entry.slice(0, entry.length - extname(entry).length),
			entry,
		]),
	),
	output: {
		format: "esm",
		dir: OUTPUT_DIR,
	},
});

// #endregion