Skip to content

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

TypeScript

feat(template-viewer): lightweight Vite app to preview CLI templates by URL path (#4510)

Kenton Quatman0503c57f70dc
diff --git a/apps/template-viewer/.gitignore b/apps/template-viewer/.gitignore
new file mode 100644
index 0000000000..40cd7827fe
--- /dev/null
+++ b/apps/template-viewer/.gitignore
@@ -0,0 +1,4 @@
+node_modules
+dist
+dist-ssr
+*.local
diff --git a/apps/template-viewer/README.md b/apps/template-viewer/README.md
new file mode 100644
index 0000000000..1fd20832db
--- /dev/null
+++ b/apps/template-viewer/README.md
@@ -0,0 +1,37 @@
+<!-- Copyright (c) Meta Platforms, Inc. and affiliates. -->
+
+# Template Viewer
+
+A tiny Vite app that renders any template from `packages/cli/templates` in the
+browser. Replaces the heavier `apps/sandbox` for previewing templates.
+
+## Usage
+
+```bash
+pnpm -F @astryxdesign/template-viewer dev
+```
+
+Then open the path to a template directory as the URL, e.g.:
+
+- http://localhost:5173/packages/cli/templates/pages/ai-chat
+- http://localhost:5173/packages/cli/templates/blocks/components/Avatar
+
+Opening `/` lists every available template.
+
+## How it works
+
+`src/App.tsx` globs every `.tsx` under `packages/cli/templates`, matches the one
+in the directory named by the URL path, and lazy-renders it inside `<Theme>`.
+StyleX is compiled from `@astryxdesign/core` source by `astryxStylex()` — no
+codegen, no Babel/PostCSS/Next.js.
+
+## Prerequisites
+
+The `@astryxdesign/build`, `@astryxdesign/core`, and `@astryxdesign/theme-neutral`
+packages must be built once (they ship from `dist`):
+
+```bash
+pnpm -F @astryxdesign/build build
+pnpm -F @astryxdesign/core build
+pnpm -F @astryxdesign/theme-neutral build
+```
diff --git a/apps/template-viewer/index.html b/apps/template-viewer/index.html
new file mode 100644
index 0000000000..9da07998c6
--- /dev/null
+++ b/apps/template-viewer/index.html
@@ -0,0 +1,14 @@
+<!-- Copyright (c) Meta Platforms, Inc. and affiliates. -->
+
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Astryx Template Viewer</title>
+ </head>
+ <body>
+ <div id="root"></div>
+ <script type="module" src="/src/main.tsx"></script>
+ </body>
+</html>
diff --git a/apps/template-viewer/package.json b/apps/template-viewer/package.json
new file mode 100644
index 0000000000..e8b961927b
--- /dev/null
+++ b/apps/template-viewer/package.json
@@ -0,0 +1,28 @@
+{
+ "name": "@astryxdesign/template-viewer",
+ "version": "0.0.1",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "dev": "vite",
+ "build": "vite build",
+ "preview": "vite preview"
+ },
+ "dependencies": {
+ "@astryxdesign/core": "*",
+ "@astryxdesign/theme-neutral": "*",
+ "@heroicons/react": "^2.2.0",
+ "@stylexjs/stylex": "^0.19.0",
+ "react": "^19.2.7",
+ "react-dom": "^19.2.7"
+ },
+ "devDependencies": {
+ "@astryxdesign/build": "*",
+ "@stylexjs/unplugin": "^0.19.0",
+ "@types/react": "^19.2.17",
+ "@types/react-dom": "^19.2.3",
+ "@vitejs/plugin-react": "^5.2.0",
+ "typescript": "^6.0.3",
+ "vite": "^8.1.3"
+ }
+}
diff --git a/apps/template-viewer/src/App.tsx b/apps/template-viewer/src/App.tsx
new file mode 100644
index 0000000000..7c5953cd53
--- /dev/null
+++ b/apps/template-viewer/src/App.tsx
@@ -0,0 +1,64 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {Suspense, lazy} from 'react';
+import type {ComponentType} from 'react';
+import {Theme} from '@astryxdesign/core/theme';
+import {LayerProvider} from '@astryxdesign/core/Layer';
+import {neutralTheme} from '@astryxdesign/theme-neutral/built';
+
+// Every renderable template, keyed by its path relative to this file, e.g.
+// "../../../packages/cli/templates/pages/ai-chat/page.tsx".
+const templates = import.meta.glob('../../../packages/cli/templates/**/*.tsx');
+
+// The URL pathname is a template directory,
+// e.g. /packages/cli/templates/pages/ai-chat
+const dir = window.location.pathname.replace(/^\/+|\/+$/g, '');
+
+// Each directory holds a single .tsx, so a substring match uniquely finds it.
+const key = dir
+ ? Object.keys(templates).find(path => path.includes(`/${dir}/`))
+ : undefined;
+
+export default function App() {
+ if (!key) {
+ return <Index />;
+ }
+
+ const Template = lazy(
+ templates[key] as () => Promise<{default: ComponentType}>,
+ );
+
+ return (
+ <Theme theme={neutralTheme}>
+ <LayerProvider>
+ <Suspense fallback={null}>
+ <Template />
+ </Suspense>
+ </LayerProvider>
+ </Theme>
+ );
+}
+
+// Fallback list of every template when the URL doesn't point at one.
+function Index() {
+ const dirs = [
+ ...new Set(
+ Object.keys(templates).map(path =>
+ path.slice(path.indexOf('packages/')).replace(/\/[^/]+$/, ''),
+ ),
+ ),
+ ].sort();
+
+ return (
+ <main style={{padding: '2rem', fontFamily: 'system-ui', lineHeight: 1.8}}>
+ <h1>Astryx Templates</h1>
+ <ul>
+ {dirs.map(d => (
+ <li key={d}>
+ <a href={`/${d}`}>{d}</a>
+ </li>
+ ))}
+ </ul>
+ </main>
+ );
+}
diff --git a/apps/template-viewer/src/index.css b/apps/template-viewer/src/index.css
new file mode 100644
index 0000000000..3c614f2227
--- /dev/null
+++ b/apps/template-viewer/src/index.css
@@ -0,0 +1,6 @@
+/* Copyright (c) Meta Platforms, Inc. and affiliates. */
+
+/* Placeholder to ensure Vite emits a CSS asset for StyleX aggregation. */
+:root {
+ --stylex-injection: 0;
+}
diff --git a/apps/template-viewer/src/main.tsx b/apps/template-viewer/src/main.tsx
new file mode 100644
index 0000000000..0a283c4620
--- /dev/null
+++ b/apps/template-viewer/src/main.tsx
@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {StrictMode} from 'react';
+import {createRoot} from 'react-dom/client';
+import '@astryxdesign/core/reset.css';
+import '@astryxdesign/theme-neutral/theme.css';
+import './index.css';
+import App from './App';
+
+// eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- root element must exist in index.html
+createRoot(document.getElementById('root')!).render(
+ <StrictMode>
+ <App />
+ </StrictMode>,
+);
diff --git a/apps/template-viewer/tsconfig.app.json b/apps/template-viewer/tsconfig.app.json
new file mode 100644
index 0000000000..973af46fc2
--- /dev/null
+++ b/apps/template-viewer/tsconfig.app.json
@@ -0,0 +1,31 @@
+{
+ "compilerOptions": {
+ "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+ "target": "ES2020",
+ "useDefineForClassFields": true,
+ "lib": ["ES2020", "DOM", "DOM.Iterable"],
+ "module": "ESNext",
+ "skipLibCheck": true,
+
+ /* Bundler mode */
+ "moduleResolution": "bundler",
+ "allowImportingTsExtensions": true,
+ "verbatimModuleSyntax": false,
+ "moduleDetection": "force",
+ "noEmit": true,
+ "jsx": "react-jsx",
+
+ /* Linting */
+ "strict": true,
+ "noUnusedLocals": true,
+ "noUnusedParameters": true,
+ "noFallthroughCasesInSwitch": true,
+
+ /* Monorepo: resolve @astryxdesign packages to source */
+ "paths": {
+ "@astryxdesign/core/*": ["../../packages/core/src/*"],
+ "@astryxdesign/core": ["../../packages/core/src"]
+ }
+ },
+ "include": ["src"]
+}
diff --git a/apps/template-viewer/tsconfig.json b/apps/template-viewer/tsconfig.json
new file mode 100644
index 0000000000..b3de6fde91
--- /dev/null
+++ b/apps/template-viewer/tsconfig.json
@@ -0,0 +1,7 @@
+{
+ "files": [],
+ "references": [
+ {"path": "./tsconfig.app.json"},
+ {"path": "./tsconfig.node.json"}
+ ]
+}
diff --git a/apps/template-viewer/tsconfig.node.json b/apps/template-viewer/tsconfig.node.json
new file mode 100644
index 0000000000..b759e6b58b
--- /dev/null
+++ b/apps/template-viewer/tsconfig.node.json
@@ -0,0 +1,24 @@
+{
+ "compilerOptions": {
+ "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+ "target": "ES2022",
+ "lib": ["ES2023"],
+ "module": "ESNext",
+ "skipLibCheck": true,
+ "types": ["node"],
+
+ /* Bundler mode */
+ "moduleResolution": "bundler",
+ "allowImportingTsExtensions": true,
+ "verbatimModuleSyntax": false,
+ "moduleDetection": "force",
+ "noEmit": true,
+
+ /* Linting */
+ "strict": true,
+ "noUnusedLocals": true,
+ "noUnusedParameters": true,
+ "noFallthroughCasesInSwitch": true
+ },
+ "include": ["vite.config.ts"]
+}
diff --git a/apps/template-viewer/vite.config.ts b/apps/template-viewer/vite.config.ts
new file mode 100644
index 0000000000..e11589a225
--- /dev/null
+++ b/apps/template-viewer/vite.config.ts
@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {defineConfig} from 'vite';
+import react from '@vitejs/plugin-react';
+import {astryxStylex} from '@astryxdesign/build/vite';
+
+export default defineConfig({
+ plugins: [...astryxStylex(), react()],
+ // Templates live outside this app's root (packages/cli/templates).
+ server: {fs: {allow: ['../..']}},
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 0a7d54b9cc..cb06ad5e67 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -374,6 +374,49 @@ importers:
specifier: ^10.4.6
version: 10.4.6(@testing-library/[email protected])(@types/[email protected])([email protected])([email protected])
+ apps/template-viewer:
+ dependencies:
+ '@astryxdesign/core':
+ specifier: '*'
+ version: link:../../packages/core
+ '@astryxdesign/theme-neutral':
+ specifier: '*'
+ version: link:../../packages/themes/neutral
+ '@heroicons/react':
+ specifier: ^2.2.0
+ version: 2.2.0([email protected])
+ '@stylexjs/stylex':
+ specifier: ^0.19.0
+ version: 0.19.0
+ react:
+ specifier: ^19.2.7
+ version: 19.2.7
+ react-dom:
+ specifier: ^19.2.7
+ version: 19.2.7([email protected])
+ devDependencies:
+ '@astryxdesign/build':
+ specifier: '*'
+ version: link:../../packages/build
+ '@stylexjs/unplugin':
+ specifier: ^0.19.0
+ '@types/react':
+ specifier: ^19.2.17
+ version: 19.2.17
+ '@types/react-dom':
+ specifier: ^19.2.3
+ version: 19.2.3(@types/[email protected])
+ '@vitejs/plugin-react':
+ specifier: ^5.2.0
+ typescript:
+ specifier: ^6.0.3
+ version: 6.0.3
+ vite:
+ specifier: ^8.1.3
+
internal/eslint-plugin-astryx:
dependencies:
eslint: