Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

refactor(cli): rename config file xds.config.mjs -> astryx.config.mjs (#3017)

EJ Hammond488eaf77138c
diff --git a/.changeset/astryx-config-file.md b/.changeset/astryx-config-file.md
new file mode 100644
index 0000000000..537554deea
--- /dev/null
+++ b/.changeset/astryx-config-file.md
@@ -0,0 +1,11 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[breaking] Read project config from `astryx.config.mjs` (was `xds.config.mjs`)
+@ejhammond
+
+The CLI now resolves its optional project config from `astryx.config.mjs`
+instead of `xds.config.mjs` — a hard cut, no fallback. Consumers with an
+`xds.config.mjs` must rename it to `astryx.config.mjs` (the config shape and
+all fields are unchanged). Part of removing `xds` naming from the public API.
diff --git a/apps/sandbox/.gitignore b/apps/sandbox/.gitignore
index 2927789959..b111587c53 100644
--- a/apps/sandbox/.gitignore
+++ b/apps/sandbox/.gitignore
@@ -2,7 +2,7 @@ node_modules
# Auto-generated by `xds init --features agents` (postinstall)
AGENTS.md
-xds.config.mjs
+astryx.config.mjs
.claude/CLAUDE.md
/pages
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 02e587abd9..01d9e6a7e2 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -155,7 +155,7 @@ if (isError(result)) {
| `ERR_WRITE_FAILED` | Writing output files failed (and was rolled back). |
| `ERR_THEME_INVALID` | A theme definition was missing a required property (e.g. `name`). |
| `ERR_THEME_LOAD` | A theme file could not be loaded / parsed into a `defineTheme` result. |
-| `ERR_TEMPLATE_CONFIG` | `template.get` is not configured in `xds.config.mjs` (fetch-by-id). |
+| `ERR_TEMPLATE_CONFIG` | `template.get` is not configured in `astryx.config.mjs` (fetch-by-id). |
| `ERR_TEMPLATE_GET` | A configured `template.get` threw or returned an invalid value. |
| `ERR_VERSION_DETECT` | The current `@astryxdesign/core` version could not be detected. |
| `ERR_INVALID_VERSION` | A `--from`/`--to` value was not a valid semver string. |
@@ -342,8 +342,8 @@ xds doctor — diagnosing your setup
⚠ Theme packages
No @astryxdesign/theme-* packages are installed.
→ fix: Install a theme, e.g. `npm install @astryxdesign/theme-default`, then import its CSS or set xds.theme.
- ℹ xds.config.mjs
- No xds.config.mjs found — using defaults.
+ ℹ astryx.config.mjs
+ No astryx.config.mjs found — using defaults.
ℹ AI agent docs
No agent docs (CLAUDE.md / AGENTS.md / .cursorrules) found.
→ fix: Generate agent docs with `xds init --features agents`.
@@ -365,7 +365,7 @@ No failures — but review the ⚠ warnings above when you can.
| @astryxdesign/core installed | pass / fail | `@astryxdesign/core` is resolvable from the project |
| Version alignment | pass / warn / info | Installed `@astryxdesign/core` is in step with `@astryxdesign/cli` |
| Theme packages | pass / warn | An `@astryxdesign/theme-*` package is installed and a theme is wired |
-| xds.config.mjs | pass / fail / info | Config (if present) loads cleanly with a valid shape |
+| astryx.config.mjs | pass / fail / info | Config (if present) loads cleanly with a valid shape |
| AI agent docs | pass / warn / info | Agent docs exist and contain the XDS section markers |
| Peer dependencies | pass / warn / info | `@astryxdesign/core`'s peer deps (react, …) are installed |
| Package manager | info | Reports the detected package manager |
@@ -385,7 +385,7 @@ data: { checks, summary } }`) that AI agents and scripts can parse.
## Configuration
-The CLI reads from an optional `xds.config.mjs` in your project root:
+The CLI reads from an optional `astryx.config.mjs` in your project root:
```javascript
export default {
diff --git a/packages/cli/src/api/doctor.mjs b/packages/cli/src/api/doctor.mjs
index f69b5fed44..933d2bd80b 100644
--- a/packages/cli/src/api/doctor.mjs
+++ b/packages/cli/src/api/doctor.mjs
@@ -50,7 +50,7 @@ const _require = createRequire(import.meta.url);
* @property {string} cwd - Directory to diagnose.
* @property {string} nodeVersion - Running Node version.
* @property {string|null} coreDir - Resolved @astryxdesign/core directory, or null.
- * @property {string|null} configPath - Resolved xds.config.mjs path, or null.
+ * @property {string|null} configPath - Resolved astryx.config.mjs path, or null.
* @property {string|null} configTheme - theme value read from config, or null.
*/
@@ -251,11 +251,11 @@ export function checkThemes(ctx) {
label: 'Theme packages',
status: 'warn',
message: `Theme package(s) installed (${names}) but no theme appears wired.`,
- fix: 'Wire a theme via the `astryx.theme` field in package.json, the ASTRYX_THEME env var, or your xds.config.mjs.',
+ fix: 'Wire a theme via the `astryx.theme` field in package.json, the ASTRYX_THEME env var, or your astryx.config.mjs.',
};
}
- const source = hasConfigTheme ? 'xds.config.mjs theme' : wiring.source;
+ const source = hasConfigTheme ? 'astryx.config.mjs theme' : wiring.source;
return {
id: 'themes',
label: 'Theme packages',
@@ -265,7 +265,7 @@ export function checkThemes(ctx) {
}
/**
- * Check 5 — xds.config.mjs (if present) loads and has a valid shape.
+ * Check 5 — astryx.config.mjs (if present) loads and has a valid shape.
* @param {DoctorContext} ctx
* @returns {Promise<DoctorCheck>}
*/
@@ -273,9 +273,9 @@ export async function checkConfig(ctx) {
if (!ctx.configPath) {
return {
id: 'config',
- label: 'xds.config.mjs',
+ label: 'astryx.config.mjs',
status: 'info',
- message: 'No xds.config.mjs found — using defaults.',
+ message: 'No astryx.config.mjs found — using defaults.',
};
}
@@ -288,10 +288,10 @@ export async function checkConfig(ctx) {
if (config !== undefined && (typeof config !== 'object' || config === null)) {
return {
id: 'config',
- label: 'xds.config.mjs',
+ label: 'astryx.config.mjs',
status: 'fail',
- message: `xds.config.mjs default export is not an object (got ${typeof config}).`,
- fix: 'Export a default object from xds.config.mjs, e.g. `export default { theme: "default" };`.',
+ message: `astryx.config.mjs default export is not an object (got ${typeof config}).`,
+ fix: 'Export a default object from astryx.config.mjs, e.g. `export default { theme: "default" };`.',
};
}
// Validate that `packages`, if present, is a string or array of strings.
@@ -303,26 +303,26 @@ export async function checkConfig(ctx) {
if (bad) {
return {
id: 'config',
- label: 'xds.config.mjs',
+ label: 'astryx.config.mjs',
status: 'fail',
- message: 'xds.config.mjs `packages` must be a string or array of strings.',
+ message: 'astryx.config.mjs `packages` must be a string or array of strings.',
fix: 'Set `packages` to a path string or array of path strings.',
};
}
}
return {
id: 'config',
- label: 'xds.config.mjs',
+ label: 'astryx.config.mjs',
status: 'pass',
- message: `xds.config.mjs loaded cleanly (${path.relative(ctx.cwd, ctx.configPath) || ctx.configPath}).`,
+ message: `astryx.config.mjs loaded cleanly (${path.relative(ctx.cwd, ctx.configPath) || ctx.configPath}).`,
};
} catch (err) {
return {
id: 'config',
- label: 'xds.config.mjs',
+ label: 'astryx.config.mjs',
status: 'fail',
- message: `xds.config.mjs failed to load: ${err.message}`,
- fix: 'Fix the syntax/runtime error in xds.config.mjs so it imports cleanly.',
+ message: `astryx.config.mjs failed to load: ${err.message}`,
+ fix: 'Fix the syntax/runtime error in astryx.config.mjs so it imports cleanly.',
};
}
}
diff --git a/packages/cli/src/api/template.mjs b/packages/cli/src/api/template.mjs
index e0932df731..b533c9600c 100644
--- a/packages/cli/src/api/template.mjs
+++ b/packages/cli/src/api/template.mjs
@@ -377,7 +377,7 @@ function extractSkeleton(source) {
}
/**
- * Fetch a template by ID using the `template.get` hook in xds.config.mjs.
+ * Fetch a template by ID using the `template.get` hook in astryx.config.mjs.
* @param {string} id
* @param {object} [options]
* @param {string} [options.cwd]
@@ -391,7 +391,7 @@ export async function getTemplateById(id, options = {}) {
if (typeof getter !== 'function') {
throw new AstryxError(
'Template fetching by ID is not configured.\n' +
- 'Add a template.get function to xds.config.mjs:\n\n' +
+ 'Add a template.get function to astryx.config.mjs:\n\n' +
' export default {\n' +
' template: {\n' +
" get: async (id) => { /* return template source string */ },\n" +
diff --git a/packages/cli/src/commands/discover.mjs b/packages/cli/src/commands/discover.mjs
index ae2bcf0a22..2fd22365eb 100644
--- a/packages/cli/src/commands/discover.mjs
+++ b/packages/cli/src/commands/discover.mjs
@@ -50,7 +50,7 @@ export function registerDiscover(program) {
if (config.packages.length === 0) {
humanLog('No package directories configured.');
humanLog('');
- humanLog('Add a packages field to xds.config.mjs:');
+ humanLog('Add a packages field to astryx.config.mjs:');
humanLog('');
humanLog(' export default {');
humanLog(" packages: ['/path/to/your/libs'],");
diff --git a/packages/cli/src/commands/doctor.test.mjs b/packages/cli/src/commands/doctor.test.mjs
index 09d08e7917..8e746dd8ef 100644
--- a/packages/cli/src/commands/doctor.test.mjs
+++ b/packages/cli/src/commands/doctor.test.mjs
@@ -118,19 +118,19 @@ describe('doctor — individual checks', () => {
expect(res.status).toBe('pass');
});
- it('config: INFO when no xds.config.mjs', async () => {
+ it('config: INFO when no astryx.config.mjs', async () => {
const res = await checkConfig({cwd: tmpDir, configPath: null});
expect(res.status).toBe('info');
});
- it('config: PASS when a valid xds.config.mjs loads', async () => {
+ it('config: PASS when a valid astryx.config.mjs loads', async () => {
// Vitest intercepts dynamic import() through Vite's resolver, which can't
// serve a file written to an arbitrary tmp path at runtime. Write the
// fixture inside the package tree so Vite can resolve it, then clean up.
const fixtureDir = fs.mkdtempSync(
path.join(path.dirname(new URL(import.meta.url).pathname), '__doctor_cfg_'),
);
- const configPath = path.join(fixtureDir, 'xds.config.mjs');
+ const configPath = path.join(fixtureDir, 'astryx.config.mjs');
try {
fs.writeFileSync(configPath, 'export default { theme: "default" };');
const res = await checkConfig({cwd: fixtureDir, configPath});
@@ -143,11 +143,11 @@ describe('doctor — individual checks', () => {
}
});
- it('config: FAIL when xds.config.mjs throws on import', async () => {
+ it('config: FAIL when astryx.config.mjs throws on import', async () => {
const fixtureDir = fs.mkdtempSync(
path.join(path.dirname(new URL(import.meta.url).pathname), '__doctor_cfg_'),
);
- const configPath = path.join(fixtureDir, 'xds.config.mjs');
+ const configPath = path.join(fixtureDir, 'astryx.config.mjs');
try {
fs.writeFileSync(configPath, 'throw new Error("boom");\nexport default {};');
const res = await checkConfig({cwd: fixtureDir, configPath});
@@ -162,7 +162,7 @@ describe('doctor — individual checks', () => {
const fixtureDir = fs.mkdtempSync(
path.join(path.dirname(new URL(import.meta.url).pathname), '__doctor_cfg_'),
);
- const configPath = path.join(fixtureDir, 'xds.config.mjs');
+ const configPath = path.join(fixtureDir, 'astryx.config.mjs');
try {
fs.writeFileSync(configPath, 'export default { packages: [123] };');
const res = await checkConfig({cwd: fixtureDir, configPath});
diff --git a/packages/cli/src/commands/gap-report.mjs b/packages/cli/src/commands/gap-report.mjs
index 8d3fe02b2b..53488cd6cd 100644
--- a/packages/cli/src/commands/gap-report.mjs
+++ b/packages/cli/src/commands/gap-report.mjs
@@ -81,11 +81,11 @@ function isCancel(value) {
}
/**
- * Update or insert the gapReport key in xds.config.mjs.
+ * Update or insert the gapReport key in astryx.config.mjs.
* Preserves existing keys (e.g. theme).
*/
function writeGapReportConfig(targetDir, gapReportValue) {
- const configPath = path.join(targetDir, 'xds.config.mjs');
+ const configPath = path.join(targetDir, 'astryx.config.mjs');
if (fs.existsSync(configPath)) {
let content = fs.readFileSync(configPath, 'utf-8');
@@ -193,7 +193,7 @@ export function registerGapReport(program) {
);
} else {
// GitHub mode — remove gapReport key or set to default
- const configPath = path.join(targetDir, 'xds.config.mjs');
+ const configPath = path.join(targetDir, 'astryx.config.mjs');
if (fs.existsSync(configPath)) {
let content = fs.readFileSync(configPath, 'utf-8');
// Remove the gapReport line entirely to use default
@@ -216,7 +216,7 @@ export function registerGapReport(program) {
}
}
- p.outro('Configuration saved to xds.config.mjs');
+ p.outro('Configuration saved to astryx.config.mjs');
});
// --- main gap-report command ---
@@ -256,7 +256,7 @@ export function registerGapReport(program) {
if (!config.enabled) {
if (json) return jsonError('Gap reporting is disabled', undefined, ERROR_CODES.ERR_GAP_REPORT_FAILED);
humanLog(
- `Gap reporting is disabled (ASTRYX_GAP_REPORT=off or xds.config.mjs).\n` +
+ `Gap reporting is disabled (ASTRYX_GAP_REPORT=off or astryx.config.mjs).\n` +
`Run \`${getRunPrefix()} xds gap-report setup\` to configure.`,
);
return;
diff --git a/packages/cli/src/commands/json-contract.test.mjs b/packages/cli/src/commands/json-contract.test.mjs
index 79495ef976..8666bc9d61 100644
--- a/packages/cli/src/commands/json-contract.test.mjs
+++ b/packages/cli/src/commands/json-contract.test.mjs
@@ -96,8 +96,8 @@ describe('--json contract: rejects before side effects', () => {
expect(status).toBe(1);
const parsed = parseJson(stdout);
expect(parsed.error).toMatch(/gap-report setup/);
- // No xds.config.mjs written.
- expect(fs.existsSync(path.join(tmpDir, 'xds.config.mjs'))).toBe(false);
+ // No astryx.config.mjs written.
+ expect(fs.existsSync(path.join(tmpDir, 'astryx.config.mjs'))).toBe(false);
});
it('xds theme --json (parent, no subcommand) rejects without printing help', () => {
@@ -157,7 +157,7 @@ describe('--json contract: supported commands emit valid envelopes', () => {
// Configure gap-report so it doesn't error on "disabled" — we want to
// hit the "interactive prompt would start" branch.
fs.writeFileSync(
- path.join(tmpDir, 'xds.config.mjs'),
+ path.join(tmpDir, 'astryx.config.mjs'),
'export default { gapReport: { command: "true" } };\n',
);
const {status, stdout} = runCli(['gap-report', '--json'], {cwd: tmpDir});
diff --git a/packages/cli/src/commands/template.mjs b/packages/cli/src/commands/template.mjs
index 12e7a794ca..bb00a6042c 100644
--- a/packages/cli/src/commands/template.mjs
+++ b/packages/cli/src/commands/template.mjs
@@ -134,7 +134,7 @@ export function registerTemplate(program) {
templateCmd
.command('get')
- .description('Fetch a template by ID via the xds.config.mjs hook')
+ .description('Fetch a template by ID via the astryx.config.mjs hook')
.requiredOption('--id <id>', 'Template identifier to fetch')
.action(async (options) => {
const json = program.opts().json || false;
diff --git a/packages/cli/src/lib/config.mjs b/packages/cli/src/lib/config.mjs
index 26b04e2283..aee88d5a76 100644
--- a/packages/cli/src/lib/config.mjs
+++ b/packages/cli/src/lib/config.mjs
@@ -1,9 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file Config loader — reads xds.config.mjs from project root
+ * @file Config loader — reads astryx.config.mjs from project root
*
- * Walks up from cwd looking for xds.config.mjs.
+ * Walks up from cwd looking for astryx.config.mjs.
* Returns the config object or defaults if not found.
*/
@@ -16,13 +16,13 @@ const DEFAULTS = {
};
/**
- * Find xds.config.mjs by walking up from startDir.
+ * Find astryx.config.mjs by walking up from startDir.
* Returns the absolute path or null.
*/
export function findConfigPath(startDir = process.cwd()) {
let dir = startDir;
for (let i = 0; i < 10; i++) {
- const candidate = path.join(dir, 'xds.config.mjs');
+ const candidate = path.join(dir, 'astryx.config.mjs');
if (fs.existsSync(candidate)) return candidate;
const parent = path.dirname(dir);
if (parent === dir) break;
@@ -32,7 +32,7 @@ export function findConfigPath(startDir = process.cwd()) {
}
/**
- * Load and return the config from xds.config.mjs.
+ * Load and return the config from astryx.config.mjs.
* Returns defaults if no config file is found.
*/
export async function loadConfig(startDir = process.cwd()) {
diff --git a/packages/cli/src/lib/error-codes.mjs b/packages/cli/src/lib/error-codes.mjs
index 2455e251f1..ff0d5b20c4 100644
--- a/packages/cli/src/lib/error-codes.mjs
+++ b/packages/cli/src/lib/error-codes.mjs
@@ -159,7 +159,7 @@ export const ERROR_CODES = Object.freeze({
ERR_THEME_LOAD: 'ERR_THEME_LOAD',
// ── Template config ──────────────────────────────────────────────
- /** `template.get` is not configured in xds.config.mjs (fetch-by-id). */
+ /** `template.get` is not configured in astryx.config.mjs (fetch-by-id). */
ERR_TEMPLATE_CONFIG: 'ERR_TEMPLATE_CONFIG',
/** A configured `template.get` threw or returned an invalid value. */
ERR_TEMPLATE_GET: 'ERR_TEMPLATE_GET',
diff --git a/packages/cli/src/utils/github.mjs b/packages/cli/src/utils/github.mjs
index f108a4e367..57db45aa11 100644
--- a/packages/cli/src/utils/github.mjs
+++ b/packages/cli/src/utils/github.mjs
@@ -6,7 +6,7 @@
* Shared helpers for interacting with the GitHub CLI (`gh`).
* Used by gap-report and swizzle commands.
*
- * Gap reporting can be configured via xds.config.mjs:
+ * Gap reporting can be configured via astryx.config.mjs:
* gapReport: false — disable entirely
* gapReport: { command: './scripts/report-gap.sh' } — run custom script (receives JSON on stdin)
*
@@ -37,7 +37,7 @@ export const GAP_CATEGORIES = [
/**
* Load gap report configuration.
*
- * Priority: env var > xds.config.mjs > default (GitHub issue)
+ * Priority: env var > astryx.config.mjs > default (GitHub issue)
*
* Returns { enabled: boolean, command?: string }
* - enabled: false → gap reporting disabled
@@ -55,8 +55,8 @@ export function loadGapReportConfig() {
return {enabled: true, command: envVar};
}
- // 2. Check xds.config.mjs
- const configPath = path.join(process.cwd(), 'xds.config.mjs');
+ // 2. Check astryx.config.mjs
+ const configPath = path.join(process.cwd(), 'astryx.config.mjs');
if (fs.existsSync(configPath)) {
try {
const content = fs.readFileSync(configPath, 'utf-8');