chore: one knobs monorepo with devknobs in packages/devknobs

.github/workflows/ci.yml

@@ -19,7 +19,11 @@ jobs:
         with:
           node-version-file: .nvmrc
           cache: pnpm
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.14
       - run: pnpm install --frozen-lockfile
+      # Includes devknobs' build and typecheck (bun, tsc).
       - run: pnpm exec turbo run lint typecheck build
       - run: pnpm format:check
       - run: pnpm skills:check
@@ -35,7 +39,11 @@ jobs:
         with:
           node-version-file: .nvmrc
           cache: pnpm
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.14
       - run: pnpm install --frozen-lockfile
       # Storybook story tests run in real Chromium (vitest browser mode).
       - run: pnpm --filter @knobs/ui exec playwright install chromium --with-deps
+      # Storybook stories and devknobs' bun tests.
       - run: pnpm test

.github/workflows/deploy.yml

@@ -18,7 +18,12 @@ jobs:
         with:
           node-version-file: .nvmrc
           cache: pnpm
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.14
       - run: pnpm install --frozen-lockfile
+      # The site bundles devknobs from its dist.
+      - run: pnpm --filter devknobs build
       - name: Build and deploy to Cloudflare Workers
         uses: cloudflare/wrangler-action@v3
         env:

.github/workflows/preview.yml

@@ -18,7 +18,12 @@ jobs:
         with:
           node-version-file: .nvmrc
           cache: pnpm
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.14
       - run: pnpm install --frozen-lockfile
+      # The site bundles devknobs from its dist.
+      - run: pnpm --filter devknobs build
       # No VITE_OPENPANEL_CLIENT_ID: preview traffic stays out of the analytics.
       - run: pnpm --filter @knobs/web build
       - name: Upload preview version

README.md

@@ -1,8 +1,14 @@
 # knobs
 
-The marketing site for the `devknobs` npm package. <https://knobs.dev>
+The `devknobs` npm package and its site, <https://knobs.dev>, in one monorepo:
 
-A copy of [mertbuilds/web-starter](https://github.com/mertbuilds/web-starter) with everything a
+| Path                 | What                                                               |
+| -------------------- | ------------------------------------------------------------------ |
+| `packages/devknobs/` | The `devknobs` npm package ([README](packages/devknobs/README.md)) |
+| `apps/web/`          | The site, knobs.dev                                                |
+| `packages/ui/`       | The site's StyleX components                                       |
+
+The site is a copy of [mertbuilds/web-starter](https://github.com/mertbuilds/web-starter) with everything a
 landing page does not need taken out: no api, no database, no auth, no billing, no e2e. What is
 left is a TanStack Start app on Cloudflare Workers, the StyleX component package behind it, and
 the tooling that keeps both honest. The founding stack decisions are in
@@ -24,7 +30,7 @@ this repo keeps only the web half. Agent rules and workflow live in [AGENTS.md](
 
 ## Develop
 
-Prereqs: Node 24 (`nvm use`), pnpm 11 (corepack).
+Prereqs: Node 24 (`nvm use`), pnpm 11 (corepack), bun 1.3 (devknobs builds and tests with it).
 
 ```sh
 pnpm install
@@ -45,11 +51,11 @@ Local URLs come from [portless](https://portless.sh): stable named HTTPS domains
 | Command             | What it does                                                       |
 | ------------------- | ------------------------------------------------------------------ |
 | `pnpm dev`          | Web + storybook, in mprocs panes                                   |
-| `pnpm test`         | Storybook story tests in real Chromium                             |
+| `pnpm test`         | Story tests in real Chromium + devknobs' `bun test`                |
 | `pnpm lint`         | oxlint, type-aware                                                 |
 | `pnpm format:check` | oxfmt, the CI check                                                |
 | `pnpm typecheck`    | `tsc --noEmit` per package                                         |
-| `pnpm build`        | turbo build (the Workers bundle for `apps/web`)                    |
+| `pnpm build`        | turbo build (devknobs' `dist`, then the Workers bundle)            |
 | `pnpm storybook`    | Component workshop (standalone, :6006)                             |
 | `pnpm bad-day`      | Nuke node_modules + all caches, reinstall (`DRY_RUN=1` to preview) |
 | `pnpm skills:check` | Warn when dep majors drift from verified agent skills              |
@@ -61,6 +67,19 @@ Local URLs come from [portless](https://portless.sh): stable named HTTPS domains
 **Deploy.** `pnpm --filter @knobs/web deploy` builds and ships to Cloudflare Workers; a push to
 main does the same from CI.
 
+## devknobs
+
+`pnpm dev` runs the site against devknobs' source, so an edit in `packages/devknobs/src` reloads
+the page. To release a new version: bump `version` in `packages/devknobs/package.json`, add the
+`CHANGELOG.md` entry, then:
+
+```sh
+pnpm --filter devknobs build
+cd packages/devknobs
+npm pack --dry-run   # check the file list
+npm publish
+```
+
 ## Going to production: accounts checklist
 
 - [ ] **Cloudflare**: Workers; secrets `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` in GitHub

apps/web/package.json

@@ -30,7 +30,7 @@
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.5",
     "@vitejs/plugin-react": "^6.1.1",
-    "devknobs": "0.2.0",
+    "devknobs": "workspace:*",
     "oxc-transform-react": "^0.148.0",
     "typescript": "^7.0.2",
     "vite": "^8.2.2",

apps/web/src/routes/index.tsx

@@ -89,7 +89,8 @@ const PANEL = '[data-devknobs="panel"]';
 
 const DUO_CREDIT = 'https://github.com/jadon7/iphone-duo';
 
-const NOTICES = 'https://github.com/mertbuilds/devknobs/blob/main/THIRD_PARTY_NOTICES.md';
+const NOTICES =
+  'https://github.com/mertbuilds/knobs/blob/main/packages/devknobs/THIRD_PARTY_NOTICES.md';
 
 const styles = create({
   // The feature grid's own gap, so the line below it reads as a new block.
@@ -664,7 +665,7 @@ function Landing() {
         <p {...props(styles.text, styles.afterFeatures)}>{m.features_panel()}</p>
         <Hints />
         <a
-          href="https://github.com/mertbuilds/devknobs#knobs"
+          href="https://github.com/mertbuilds/knobs/tree/main/packages/devknobs#knobs"
           {...props(styles.link, styles.self, styles.withIcon)}
         >
           {m.features_readme()}
@@ -729,7 +730,7 @@ function Landing() {
       </section>
 
       <footer {...props(styles.footer)}>
-        <a href="https://github.com/mertbuilds/devknobs" {...props(styles.link, styles.withIcon)}>
+        <a href="https://github.com/mertbuilds/knobs" {...props(styles.link, styles.withIcon)}>
           <GitHubMark />
           {m.link_github()}
         </a>

apps/web/vite.config.ts

@@ -1,48 +1,27 @@
-import { existsSync, realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { cloudflare } from '@cloudflare/vite-plugin';
 import { paraglideVitePlugin } from '@inlang/paraglide-js';
 import { unplugin as stylex } from '@stylexjs/unplugin';
 import { tanstackStart } from '@tanstack/react-start/plugin/vite';
 import react from '@vitejs/plugin-react';
-import { build, defineConfig, type Plugin, searchForWorkspaceRoot } from 'vite';
-import web from './package.json' with { type: 'json' };
+import { build, defineConfig, type Plugin } from 'vite';
 import { tuneEndpoint } from './vite.tune.ts';
 
-const repoRoot = resolve(import.meta.dirname, '../..');
-
-// The dev server runs devknobs from its local checkout, so the site tests the
-// version in the works: DEVKNOBS_PATH (absolute, or relative to the repo root),
-// else `devknobs` beside this checkout, which also holds for `knobs.dev.<branch>`
-// worktrees. Builds keep the pinned npm package. The early script
-// (`devknobs/early?raw`) is built from the checkout's current source too.
-function localDevknobs(): Plugin {
-  const wanted = resolve(repoRoot, process.env.DEVKNOBS_PATH ?? '../devknobs');
-  const root = existsSync(resolve(wanted, 'src/index.ts')) ? realpathSync(wanted) : null;
+// The dev server runs devknobs from its source in packages/devknobs, so an edit
+// there reloads the page with no build. Builds use the package's dist, which
+// turbo builds first. The early script (`devknobs/early?raw`) is built from the
+// current source too.
+function devknobsSource(): Plugin {
+  const root = resolve(import.meta.dirname, '../../packages/devknobs');
+  const early = '\0devknobs-early';
   return {
     apply: (_config, { command, isPreview }) => command === 'serve' && !isPreview,
-    config() {
-      if (!root) {
-        return;
-      }
-      return {
-        resolve: { alias: [{ find: /^devknobs$/, replacement: resolve(root, 'src/index.ts') }] },
-        server: { fs: { allow: [searchForWorkspaceRoot(process.cwd()), root] } },
-      };
-    },
-    configResolved({ logger }) {
-      if (root) {
-        logger.info(`devknobs: local ${root}`);
-        return;
-      }
-      logger.info(`devknobs: npm ${web.devDependencies.devknobs} (no local checkout at ${wanted})`);
-    },
+    config: () => ({
+      resolve: { alias: [{ find: /^devknobs$/, replacement: resolve(root, 'src/index.ts') }] },
+    }),
     configureServer(server) {
-      if (!root) {
-        return;
-      }
       // The source asks for its device images beside src/engine, where the
-      // build copies them; in the checkout they sit in assets/bezels.
+      // build copies them; in the package they sit in assets/bezels.
       const from = `/@fs${root}/src/engine/bezels/`;
       server.middlewares.use((req, _res, next) => {
         if (req.url?.startsWith(from)) {
@@ -51,10 +30,10 @@ function localDevknobs(): Plugin {
         next();
       });
     },
-    // Before Vite's own `?raw` loader, which would read the npm package's dist.
+    // Before Vite's own `?raw` loader, which would read the package's dist.
     enforce: 'pre',
     async load(id) {
-      if (!root || !/\/devknobs\/dist\/early\.global\.js\?raw$/.test(id)) {
+      if (id !== early) {
         return;
       }
       const result = await build({
@@ -80,14 +59,15 @@ function localDevknobs(): Plugin {
       }
       return `export default ${JSON.stringify(chunk.code)};`;
     },
-    name: 'local-devknobs',
+    name: 'devknobs-source',
+    resolveId: (id) => (id === 'devknobs/early?raw' ? early : undefined),
   };
 }
 
 export default defineConfig({
   plugins: [
     tuneEndpoint(resolve(import.meta.dirname, '.tune')),
-    localDevknobs(),
+    devknobsSource(),
     cloudflare({ viteEnvironment: { name: 'ssr' } }),
     tanstackStart(),
     react({ compiler: true }),

docs/adr/0002-panel-tokens.md

@@ -13,5 +13,5 @@ ADR-0001 chose black/white plus 3 grays, a 4px radius and Suisse Intl (fetched,
 ## Consequences
 
 - Suisse Intl and the Inter fallback are dropped, with the font pipeline that served them: `fonts.css`, `@fontsource-variable/inter`, `scripts/fetch-fonts.sh`, `pnpm fonts` and the deploy step that fetched the files.
-- The tokens in `packages/ui/src/tokens.stylex.ts` mirror the values in the panel's stylesheet (`src/ui/styles.ts` in mertbuilds/devknobs). When the panel's values change, update the tokens to match.
+- The tokens in `packages/ui/src/tokens.stylex.ts` mirror the values in the panel's stylesheet (`packages/devknobs/src/ui/styles.ts`). When the panel's values change, update the tokens to match.
 - The 4px spacing scale from ADR-0001 stays.

lefthook.yml

@@ -3,10 +3,14 @@ pre-commit:
   jobs:
     - name: oxlint
       glob: '*.{ts,tsx,js,jsx}'
+      exclude:
+        - 'packages/devknobs/**'
       run: pnpm exec oxlint --fix {staged_files}
       stage_fixed: true
     - name: oxfmt
       glob: '*.{ts,tsx,js,jsx,json,jsonc,yaml,yml,md}'
+      exclude:
+        - 'packages/devknobs/**'
       run: pnpm exec oxfmt {staged_files}
       stage_fixed: true
 

oxfmt.config.ts

@@ -14,6 +14,8 @@ export default defineConfig({
     '.wrangler',
     'pnpm-lock.yaml',
     '.claude/skills',
+    // devknobs keeps its own style and checks (bun test, tsc).
+    'packages/devknobs',
   ],
   singleQuote: true,
 });

oxlint.config.ts

@@ -16,6 +16,8 @@ export default defineConfig({
     'apps/web/src/routeTree.gen.ts',
     'apps/web/worker-configuration.d.ts',
     '.claude/skills',
+    // devknobs keeps its own style and checks (bun test, tsc).
+    'packages/devknobs',
   ],
   overrides: [
     {

packages/devknobs/.gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+dist.tmp
+__pycache__/