An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use strict';
/**
* @astryxdesign/build/next
*
* Next.js configuration helper for Astryx source builds, under webpack or
* Turbopack.
*
* Usage in next.config.mjs:
* import {withAstryx} from '@astryxdesign/build/next';
* export default withAstryx({
* // your normal next config
* });
*/
const fs = require('fs');
const path = require('path');
const {fileURLToPath} = require('url');
const {
ASTRYX_PACKAGES,
SOURCE_PACKAGES,
findPackageDir,
sourcePackages,
stylexOptions,
} = require('./source-stylesheet');
const ASTRYX_MODULE = /[\\/]node_modules[\\/]@astryxdesign[\\/]/;
const escapeRegExp = text => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
const TURBOPACK_LOADER = require.resolve('./turbopack-loader.js');
const SWIZZLE_MARKER_LOADER = require.resolve('./swizzle-marker-loader.js');
/**
* Match a wildcard alias key such as `@astryxdesign/*` against a request. The
* resolver treats `*` as the variable part of the specifier, so a caller can
* claim a whole scope with one entry.
*/
function wildcardPattern(name) {
const source = name
.split('*')
.map(part => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
.join('.*');
return new RegExp(`^${source}$`);
}
/**
* Drop the generated aliases a caller has already spoken for. A caller entry
* is authoritative for the request it names: `'@astryxdesign/core'` is a prefix
* alias covering the package and every subpath under it,
* `'@astryxdesign/core$'` covers only the bare specifier, and
* `'@astryxdesign/*'` claims everything the pattern matches. Without this the
* generated entries sit earlier in the alias list and win, so a composed config
* silently loads astryx source instead of the caller's implementation.
*/
function withoutCallerOverrides(generated, callerAlias) {
const exact = new Set();
const prefixes = [];
const patterns = [];
for (const key of Object.keys(callerAlias)) {
const onlyModule = key.endsWith('$');
const name = onlyModule ? key.slice(0, -1) : key;
if (name.includes('*')) {
patterns.push(wildcardPattern(name));
} else if (onlyModule) {
exact.add(name);
} else {
prefixes.push(name);
}
}
const kept = {};
for (const [key, target] of Object.entries(generated)) {
const request = key.slice(0, -1);
const overridden =
exact.has(request) ||
prefixes.some(
prefix => request === prefix || request.startsWith(`${prefix}/`),
) ||
patterns.some(pattern => pattern.test(request));
if (!overridden) {
kept[key] = target;
}
}
return kept;
}
/**
* Merge the generated aliases under whatever the caller already configured.
* `resolve.alias` accepts an object or an array of entries; both are ordered,
* first match wins, so the caller's entries stay ahead of ours either way.
*/
function mergeAliases(generated, existing) {
if (Array.isArray(existing)) {
const named = {};
for (const entry of existing) {
if (entry && typeof entry.name === 'string') {
named[entry.onlyModule ? `${entry.name}$` : entry.name] = entry.alias;
}
}
const kept = withoutCallerOverrides(generated, named);
return [
...existing,
...Object.entries(kept).map(([key, alias]) => ({
name: key.slice(0, -1),
onlyModule: true,
alias,
})),
];
}
const callerAlias = existing || {};
return {...withoutCallerOverrides(generated, callerAlias), ...callerAlias};
}
/**
* Map each installed astryx package to the `source` targets in its export map,
* so an app's imports reach raw TS the way an in-repo build does. Subpaths get
* an entry each — `@astryxdesign/core/AlertDialog` is as much a documented
* entry point as the package root. Packages that are absent, and export keys
* that ship no `source` condition, are skipped and keep normal resolution.
*/
function sourceEntryAliases(packages, context) {
const from = (context && context.dir) || process.cwd();
const aliases = {};
for (const name of packages) {
// Not `require.resolve(`${name}/package.json`)`: packages that define
// `exports` without a `./package.json` key — astryx's own among them —
// make that request throw ERR_PACKAGE_PATH_NOT_EXPORTED.
const packageDir = findPackageDir(name, from);
if (packageDir == null) {
continue;
}
let exports;
try {
exports = require(path.join(packageDir, 'package.json')).exports;
} catch {
continue;
}
if (exports == null || typeof exports !== 'object') {
continue;
}
for (const [key, value] of Object.entries(exports)) {
const entry = value && typeof value === 'object' ? value.source : null;
if (typeof entry !== 'string' || key.includes('*')) {
continue;
}
const request = key === '.' ? name : `${name}/${key.slice(2)}`;
aliases[`${request}$`] = path.resolve(packageDir, entry);
}
}
return aliases;
}
/**
* Whether the resolved alias map routes any astryx request at all.
*
* The test is webpack's own matching rule rather than a list of shapes. A
* non-exact alias `key` intercepts a request `R` when `R === key` or `R` starts
* with `${key}/`, so an entry covers the packages when one of them sits at or
* below its key: `'@astryxdesign'` claims `@astryxdesign/core`. A key *under* a
* package counts too, because that is the shape of the entries this helper
* generates, and a `*` key claims by pattern, using the same matcher
* `withoutCallerOverrides` applies.
*
* Exactness — a trailing `$` on an object key, `onlyModule: true` on an array
* entry — restricts an entry to the literal request, which removes the
* ancestor case and only that one. `'@astryxdesign/core$'` still routes a real
* request; `'@astryxdesign$'` routes only the bare scope specifier, which
* nothing imports, so it covers nothing.
*
* Where a caller points its alias is its business; the only thing worth saying
* is that no entry routes the packages at all. A false positive tells someone
* their working build is broken, so an ambiguous config stays quiet — but an
* exact-scope key is not ambiguous, it is determinately ineffective.
*/
function aliasCoversAstryx(alias, packages) {
const covers = (key, exact) => {
const bare = key.endsWith('$') ? key.slice(0, -1) : key;
const isExact = exact || key.endsWith('$');
if (bare.includes('*')) {
const pattern = wildcardPattern(bare);
return packages.some(name => pattern.test(name));
}
return packages.some(
name =>
name === bare ||
bare.startsWith(`${name}/`) ||
(!isExact && name.startsWith(`${bare}/`)),
);
};
if (Array.isArray(alias)) {
return alias.some(
entry =>
entry &&
typeof entry.name === 'string' &&
covers(entry.name, entry.onlyModule === true),
);
}
if (alias == null || typeof alias !== 'object') {
return false;
}
return Object.keys(alias).some(key => covers(key, false));
}
const posix = file => file.split(path.sep).join('/');
const sourceRegExp = tails =>
new RegExp(`(^|/)(${[...new Set(tails)].map(escapeRegExp).join('|')})/`);
/**
* How a package's source path ends in the resolved, root-relative paths that
* Turbopack matches rules against. For a workspace link, the tail starts at the
* app's closest ancestor that holds the package, such as `packages/core/src`.
* For an installed package, it is the path in `node_modules`.
*/
function sourceTails(pkg, cwd) {
const real = fs.realpathSync(pkg.srcDir);
let base = fs.realpathSync(cwd);
while (path.relative(base, real).startsWith('..')) base = path.dirname(base);
return [
`node_modules/${pkg.name}/${posix(path.relative(pkg.dir, pkg.srcDir))}`,
posix(path.relative(base, real)),
];
}
/**
* Keep a caller's rule off Astryx source. Turbopack runs every rule whose glob
* matches. So a caller rule such as `*.tsx` with its own StyleX setup could
* compile Astryx again, with other class names. Next.js makes each bare loader
* in a list a rule of its own, run in list order. Wrapping each loader in place
* keeps that order on the app's files.
*/
function keepOffAstryx(collection, astryxSource) {
const exclude = rule => ({
...rule,
condition:
rule.condition == null
? {not: astryxSource}
: {all: [{not: astryxSource}, rule.condition]},
});
const isLoader = item => typeof item === 'string' || 'loader' in item;
return Array.isArray(collection)
? collection.map(item => exclude(isLoader(item) ? {loaders: [item]} : item))
: exclude(collection);
}
const ASTRYX_RULE = '*.{ts,tsx}';
const NEXT_CONFIG = /^next\.config(\.compiled)?\.[cm]?[jt]s$/;
/**
* The project directory. Webpack's hook receives it as `context.dir`. A
* Turbopack config receives no such value. Next.js loads the config file from
* the project directory and keeps the working directory (`next build <dir>`).
* So the project is that file's directory, found on the call stack. A working
* directory inside it wins. The app can import a config from an ancestor, and
* Next.js then runs in the app.
*/
function projectDir() {
const {prepareStackTrace, stackTraceLimit} = Error;
Object.assign(Error, {prepareStackTrace: (_, sites) => sites});
Error.stackTraceLimit = Infinity;
const sites = new Error().stack;
Object.assign(Error, {prepareStackTrace, stackTraceLimit});
const config = sites
.map(site => site.getFileName() ?? '')
.map(file => (file.startsWith('file:') ? fileURLToPath(file) : file))
.find(file => NEXT_CONFIG.test(path.basename(file)));
const [cwd, dir] = [process.cwd(), config && path.dirname(config)];
return dir && !`${cwd}${path.sep}`.startsWith(`${dir}${path.sep}`)
? dir
: cwd;
}
/**
* The Turbopack half. Turbopack never calls `nextConfig.webpack`, so this
* configures Turbopack directly. `resolveAlias` points each documented entry
* point at its `source` file, unless the caller aliased it. Turbopack matches
* alias keys exactly and resolves targets from the project directory. A rule
* per package compiles its source with the prebuilt stylesheets' StyleX
* options. Every caller rule stays off that source.
*/
function turbopackConfig(turbopack = {}, cwd) {
const packages = sourcePackages(cwd);
if (packages.length === 0) {
return turbopack;
}
const callerAlias = turbopack.resolveAlias || {};
const claimed = Object.keys(callerAlias)
.filter(key => key.includes('*'))
.map(wildcardPattern);
const resolveAlias = {};
for (const {entries} of packages) {
for (const [request, file] of entries) {
if (request in callerAlias || claimed.some(p => p.test(request))) {
continue;
}
const target = posix(path.relative(cwd, file));
resolveAlias[request] = target.startsWith('../') ? target : `./${target}`;
}
}
Object.assign(resolveAlias, callerAlias);
const tails = packages.map(pkg => sourceTails(pkg, cwd));
const astryxSource = {path: sourceRegExp(tails.flat())};
const rules = {};
for (const [glob, collection] of Object.entries(turbopack.rules || {})) {
rules[glob] = keepOffAstryx(collection, astryxSource);
}
rules[ASTRYX_RULE] = [
...[rules[ASTRYX_RULE] ?? []].flat(),
...packages.map((pkg, i) => ({
condition: {path: sourceRegExp(tails[i])},
loaders: [
{loader: TURBOPACK_LOADER, options: stylexOptions(pkg, packages)},
],
as: '*',
})),
];
return {...turbopack, resolveAlias, rules};
}
/**
* Wraps a Next.js config to enable Astryx source builds.
* - Adds transpilePackages for @astryxdesign/* packages
* - webpack: sets conditionNames and aliases to resolve source exports
* - Turbopack: see `turbopackConfig()`
*/
function withAstryx(nextConfig = {}) {
const astryxPackages = ASTRYX_PACKAGES;
const existingTranspile = nextConfig.transpilePackages || [];
const merged = Array.from(new Set([...existingTranspile, ...astryxPackages]));
// Next sets TURBOPACK whenever it bundles with Turbopack (its default since
// Next 16) and leaves it unset under `--webpack`.
if (process.env.TURBOPACK) {
// The webpack setup's PostCSS plugin reads this and refuses to run.
process.env.ASTRYX_BUILD_TURBOPACK = '1';
return {
...nextConfig,
transpilePackages: Array.from(
new Set([...existingTranspile, ...SOURCE_PACKAGES]),
),
turbopack: turbopackConfig(nextConfig.turbopack, projectDir()),
};
}
const existingWebpack = nextConfig.webpack;
return {
...nextConfig,
transpilePackages: merged,
webpack: (config, context) => {
// Astryx packages are consumed from their `source` export (raw TS) so
// the sandbox/docsite build straight from src without a prebuild step.
// Apply the `source` condition via a scoped, ALLOWLIST rule that only
// matches @astryxdesign packages — the global conditions stay as Next's
// defaults (webpack's `'...'` sentinel + react-server), which React JSX
// resolution depends on. Third-party deps (e.g. `lexical`, which also
// ships a `source` export) therefore resolve to their built output, not
// raw TS. This is robust to new third-party `source`-shipping deps.
config.module = config.module || {};
config.module.rules = config.module.rules || [];
// `Rule.test` matches the module being processed, by the path the
// resolver reports, and webpack reports a symlinked package by its real
// path. Under pnpm's isolated layout that path still runs through
// `node_modules/@astryxdesign/`, but a workspace link's does not
// (`packages/core/...`), so the rule also matches each installed
// package's real directory.
const from = (context && context.dir) || process.cwd();
const realPackageDirs = astryxPackages
.map(name => findPackageDir(name, from))
.filter(dir => dir != null)
.map(dir => escapeRegExp(fs.realpathSync(dir) + path.sep));
// The app's own modules depend on the swizzle markers above them, so a
// cached build recompiles a copy when its marker appears or disappears.
config.module.rules.unshift({
test: /\.[cm]?[jt]sx?$/,
exclude: /[\\/]node_modules[\\/]/,
enforce: 'pre',
use: [{loader: SWIZZLE_MARKER_LOADER}],
});
config.module.rules.unshift({
test:
realPackageDirs.length === 0
? ASTRYX_MODULE
: new RegExp(
`${ASTRYX_MODULE.source}|^(?:${realPackageDirs.join('|')})`,
),
resolve: {
conditionNames: ['source', '...'],
},
});
// The rule above only covers astryx-to-astryx imports: `Rule.test`
// matches the module being processed and `Rule.resolve` governs the
// requests that module makes, so an app's own `@astryxdesign/*` imports —
// issued from its sources, outside node_modules — never match it. Those
// resolve through `default` to dist, whose runtime class names are
// disjoint from the CSS the PostCSS pass compiles out of source, and the
// app renders unstyled without erroring. Rules cannot key on the request
// string, so point the packages at their `source` entry directly; the
// global conditions stay as Next's defaults for React and for
// third-party `source` shippers such as `lexical`.
config.resolve = config.resolve || {};
// Leave `resolve.symlinks` at webpack's default (true). Under pnpm's
// isolated layout a package's own dependencies (`intl-messageformat`
// for Core, `lucide-react` for the neutral theme) sit beside its real
// path, not under the app's `node_modules`, so resolving from the
// symlink path cannot find them.
// Call user's webpack config if provided
const merged = existingWebpack
? existingWebpack(config, context) || config
: config;
// Merge after the caller's hook, not before: aliases the hook adds are
// as authoritative as the ones already on the config, and merging first
// would leave the generated entries ahead of them in the alias list —
// where the resolver, taking the first match, loads astryx source
// instead. Only a byte-identical `$` key would have replaced ours.
merged.resolve = merged.resolve || {};
merged.resolve.alias = mergeAliases(
sourceEntryAliases(astryxPackages, context),
merged.resolve.alias,
);
// Generating no entries is not itself a fault: a package may simply not be
// installed, and a caller alias that already routes the packages is a
// working config this helper has nothing to add to. What is a fault is
// ending up with an alias map that claims none of them — that is the
// pre-0.5.3 config, where the app resolves dist while PostCSS compiles the
// library from source and the page renders unstyled with nothing logged.
// So the check is on the merged result, not on what we generated, and it
// warns rather than throws: an install layout this helper cannot walk is
// not proof the build is wrong.
if (!aliasCoversAstryx(merged.resolve.alias, astryxPackages)) {
console.warn(
'[@astryxdesign/build] withAstryx(): no alias routes ' +
`${astryxPackages.join(', ')} to their \`source\` entries. Either they ` +
'are not installed where the app can see them, their export maps ' +
'ship no `source` condition, or a configured alias does not match ' +
'the requests — an exact key such as `@astryxdesign$` matches only ' +
'the bare specifier. Source resolution is not in effect, so the app ' +
'will load dist while the PostCSS pass compiles the library from ' +
'source.',
);
}
return merged;
},
};
}
module.exports = {withAstryx};