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 @astryxdesign/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.

Requires pnpm. Install (npm i -g pnpm) or prefix every pnpm command with npx.

---

How to test as an external consumer

1. Build and pack from the repo root

pnpm install
pnpm build

pnpm -F @astryxdesign/core          pack --out "/tmp/%s.tgz"
pnpm -F @astryxdesign/theme-default pack --out "/tmp/%s.tgz"
pnpm -F @astryxdesign/build         pack --out "/tmp/%s.tgz"

2. Set up a standalone test directory

mkdir ~/astryx-test-app
cd ~/astryx-test-app

3. Copy the example app files

Use rsync to skip node_modules (which is huge and contains symlink cycles):

# Vite:
rsync -a --exclude node_modules --exclude dist /path/to/astryx/apps/example-vite/ .
# Next.js:
rsync -a --exclude node_modules --exclude .next /path/to/astryx/apps/example-nextjs/ .

4. Update package.json to use the tarballs

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

For the Vite example, you'll need build as wel:

{
  "devDependencies": {
    "@astryxdesign/build": "file:/tmp/astryxdesign-build.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/@astryxdesign/core/src (same as consumer)	Point to node_modules/@astryxdesign/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