Testing Example Apps

Testing Example Apps

The example apps (apps/example-vite, apps/example-nextjs) live inside the Astryx monorepo but are intended to represent what an external consumer experiences when installing @xds/core from npm. Because of how monorepo workspaces work, the example apps may silently bypass issues that real consumers hit — workspace symlinks resolve outside node_modules, Vite skips pre-bundling for workspace packages, and shared node_modules hoisting can mask missing dependencies.

Any change to an example app should be tested as an external consumer, not just inside the monorepo.

---

How to test as an external consumer

1. Build and pack the packages

From the repo root:

# Build core (compiles JS + extracts CSS)
pnpm build

# Pack into tarballs
cd packages/core && pnpm pack --pack-destination /tmp/xds-core.tgz
cd packages/themes/default && pnpm pack --pack-destination /tmp/xds-theme-default.tgz

2. Set up a standalone test directory

Create a directory outside the monorepo:

mkdir ~/xds-test-app
cd ~/xds-test-app

3. Copy the example app files

Copy the example's source files, configs, and package.json into the test directory:

# For the Vite example:
cp -r /path/to/xds/apps/example-vite/* ~/xds-test-app/
# Or for the Next.js example:
cp -r /path/to/xds/apps/example-nextjs/* ~/xds-test-app/

4. Update package.json to use tarballs

Replace the workspace references with tarball paths:

{
  "dependencies": {
    "@xds/core": "file:/tmp/xds-core.tgz",
    "@xds/theme-default": "file:/tmp/xds-theme-default.tgz"
  }
}

5. Install and run

npm install
# Vite:
npx vite build && npx vite preview
# Next.js:
npx next build && npx next start

6. What to verify

• No runtime errors — especially "Unexpected stylex.defineVars call at runtime" (means Vite pre-bundled Astryx before StyleX could compile it)
• Colors render correctly — check that light-dark() tokens aren't broken (invisible text, missing backgrounds). Inspect the CSS for --lightningcss-light polyfill variables — if present without initialization, the lightningcss targets are wrong
• Dark mode works — toggle color-scheme in devtools or wrap with <Theme mode="dark"> and verify colors switch
• All CSS layers present — check for @layer reset, @layer typography, and StyleX priority layers in the output CSS
• Theme overrides apply — verify the theme's component overrides (e.g. heading sizes, button styles) are active

---

Known differences between monorepo and external consumer

Concern	In monorepo	As external consumer
Package resolution	Workspace symlinks (outside node_modules)	Real node_modules path
Vite dep optimization	Skipped for workspace packages	Pre-bundles node_modules packages (breaks StyleX if not excluded)
StyleX dependency	Available via workspace hoisting	Must be in consumer's devDependencies
Resolve aliases	Point to node_modules/@xds/core/src (same as consumer)	Point to node_modules/@xds/core/src
lightningcss targets	May not matter (monorepo has targets set)	Required — StyleX unplugin defaults to old browser targets

---

Checklist for example app changes

Before merging changes to an example app:

• Tested outside the monorepo using the tarball flow above
• No monorepo-specific paths in configs (../../packages/ etc.)
• package.json dependencies use package names, not file: or *
• README inline config examples match the actual config files
• Any new config requirements are documented in the Gotchas table