create-react-native-library-template 0.1.0 → 0.1.3

package/README.md

@@ -9,7 +9,7 @@ bun create react-native-library-template my-library
 
 ## What you get
 
-- **Bun workspaces** monorepo: the library (`packages/ui`), a web Storybook (`apps/storybook`), and an Expo app running Storybook on device (`apps/native`).
+- **Bun workspaces** monorepo: the library (`packages/ui`), a web Storybook (`storybook/web`), and an Expo app running Storybook on device (`storybook/native`).
 - **Storybook 10** on web (react-native-web + Vite) and native, sharing the same CSF3 stories.
 - **Vitest** unit tests (jsdom + react-native-web) and story tests (browser mode, `play` functions).
 - **Biome** linting/formatting, **TypeScript** strict mode.

package/index.mjs

@@ -51,8 +51,9 @@ Scaffolded ${projectName} in ${targetDir}
 
 Next steps:
   cd ${target}
+  git init
   bun install
-  git init && git add -A && git commit -m "Initial commit"
+  git add -A && git commit -m "Initial commit"
 
 Useful commands:
   bun run storybook          # web Storybook at http://localhost:6006

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-react-native-library-template",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Scaffold a React Native UI library monorepo: Bun workspaces, Expo, Storybook (web + native), Vitest, Biome and Changesets",
   "license": "MIT",
   "type": "module",

package/template/.github/workflows/deploy-storybook.yml

@@ -0,0 +1,47 @@
+name: Deploy Storybook
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    name: Build web Storybook
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build Storybook
+        run: bun run --cwd storybook/web build-storybook
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: storybook/web/storybook-static
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

package/template/.husky/pre-commit

@@ -0,0 +1,3 @@
+bun run lint
+bun run typecheck
+bun run test:unit

package/template/AGENTS.md

@@ -4,14 +4,15 @@ Monorepo for a publishable React Native UI library. Bun workspaces:
 
 | Workspace | Package | Purpose |
 | --- | --- | --- |
-| `packages/ui` | `@template/ui` | The library. The only published package. |
-| `apps/storybook` | `@template/storybook-web` | Web Storybook (react-native-web + Vite) and Storybook tests (Vitest browser mode). |
-| `apps/native` | `@template/example` | Expo app running Storybook React Native on device. |
+| `packages/ui` | `@template/ui` | The library. Versioned by changesets but `private` (see [Releasing](#releasing)). |
+| `storybook/web` | `@template/storybook-web` | Web Storybook (react-native-web + Vite) and Storybook tests (Vitest browser mode). |
+| `storybook/native` | `@template/example` | Expo app running Storybook React Native on device. |
 
 Tooling: **bun** (package manager + script runner), **biome** (lint + format), **TypeScript 6**
 (strict, `verbatimModuleSyntax` — use `import type` for types), **vitest** (unit tests via
 react-native-web in jsdom; story tests via `@storybook/addon-vitest` in Chromium),
-**react-native-builder-bob** (library build), **changesets** (versioning/publishing).
+**react-native-builder-bob** (library build), **changesets** (versioning/publishing),
+**husky** (git hooks — a `pre-commit` hook runs lint, typecheck, and unit tests).
 
 ## Commands (run from the repo root)
 
@@ -34,32 +35,44 @@ Follow the `Button` component (`packages/ui/src/components/Button/`) as the refe
 implementation. For a component named `Foo`:
 
 1. **Create the folder** `packages/ui/src/components/Foo/` containing exactly:
-   - `Foo.tsx` — the component.
-   - `Foo.test.tsx` — vitest unit tests.
-   - `Foo.stories.tsx` — Storybook stories (CSF3), including at least one `play` function.
-   - `index.ts` — re-exports: `export { Foo, type FooProps } from './Foo';`
-2. **Write the component** (`Foo.tsx`):
+   - `foo.tsx` — the component.
+   - `foo.test.tsx` — vitest unit tests.
+   - `foo.stories.tsx` — Storybook stories (CSF3), including at least one `play` function.
+
+   **No `index.ts`** — barrel files are forbidden everywhere in the library. Public entry
+   points are declared in the `exports` map of `packages/ui/package.json` (step 3), and
+   internal imports always target the concrete file (`../../theme/tokens`), never a folder.
+2. **Write the component** (`foo.tsx`):
    - Named function export (`export function Foo(...)`), never a default export.
    - Export a `FooProps` interface with a JSDoc comment per prop; document defaults with `@default`.
    - Only import from `react`, `react-native`, and internal modules. New runtime dependencies
      need explicit approval — they become dependencies for every consumer of the library.
    - Use only RN APIs that exist on react-native-web (`View`, `Text`, `Pressable`,
      `StyleSheet`, ...), otherwise unit tests and the web Storybook will break.
-   - Style with `StyleSheet.create` and the design tokens from `src/theme` (`colors`,
+   - Style with `StyleSheet.create` and the design tokens from `src/theme/tokens.ts` (`colors`,
      `spacing`, `radii`, `fontSizes`) — no hard-coded colors or magic numbers. Add new tokens
      to `src/theme/tokens.ts` if needed.
    - Accessibility is required: set `accessibilityRole`, `accessibilityState`, and accept an
      `accessibilityLabel` prop. Also accept `style` (as `StyleProp<...>`) and `testID`.
-3. **Export it from the library**: add `export * from './components/Foo';` to
-   `packages/ui/src/index.ts`.
-4. **Write stories** (`Foo.stories.tsx`):
+3. **Export it from the library**: add a `./foo` subpath to the `exports` map in
+   `packages/ui/package.json`, mirroring the existing `./button` entry:
+   ```json
+   "./foo": {
+     "source": "./src/components/Foo/foo.tsx",
+     "types": "./lib/typescript/components/Foo/foo.d.ts",
+     "default": "./lib/module/components/Foo/foo.js"
+   }
+   ```
+   Consumers then use `import { Foo } from '@template/ui/foo'`. There is no root entry
+   point and no `src/index.ts` — never add one.
+4. **Write stories** (`foo.stories.tsx`):
    - CSF3 with `satisfies Meta<typeof Foo>` and `StoryObj<typeof meta>`; title `Components/Foo`.
    - Set default `args` for every prop; use `fn()` from `storybook/test` for callbacks.
    - One story per visual variant/state, plus interaction stories with `play` functions
      asserting behavior (`within`, `userEvent`, `expect` from `storybook/test`).
    - Stories are shared by the web and native Storybooks — keep them platform-neutral and
      import types only from `@storybook/react` (type-only imports are erased at runtime).
-5. **Write unit tests** (`Foo.test.tsx`) with `@testing-library/react`. They run in jsdom with
+5. **Write unit tests** (`foo.test.tsx`) with `@testing-library/react`. They run in jsdom with
    `react-native` aliased to `react-native-web`. Query by accessible role/name
    (`screen.getByRole('button', { name: ... })`), and cover: rendering, interaction callbacks,
    and disabled/edge states.
@@ -75,23 +88,26 @@ implementation. For a component named `Foo`:
 
 CI (`.github/workflows/ci.yml`) runs lint, typecheck, tests, build, and Storybook tests on
 every PR. On pushes to `main`, `.github/workflows/release.yml` uses changesets to open/update
-a "Version Packages" PR; merging it publishes `@template/ui` to npm (requires the `NPM_TOKEN`
-repository secret). Never edit versions in `package.json` or `CHANGELOG.md` by hand.
+a "Version Packages" PR; merging it versions `@template/ui` and writes its changelog (the
+library itself stays `private`, so `changeset publish` skips it — this is a template repo,
+the library is for scaffolded projects). The Version PR also bumps the scaffolder version;
+the next push to `main` publishes `create-react-native-library-template` to npm (requires
+`NPM_TOKEN`). Scaffolded projects follow the same flow — rename the `@template/*` packages
+to your own npm scope and set `NPM_TOKEN`. Never edit versions in `package.json` or
+`CHANGELOG.md` by hand.
+`.github/workflows/deploy-storybook.yml` builds the web Storybook (`storybook/web`) on every
+push to `main` and deploys it to GitHub Pages (repo Settings → Pages → Source: GitHub Actions).
 
 ## Gotchas
 
-- `apps/native/.rnstorybook/storybook.requires.ts` is generated (by Metro or
-  `bun run --cwd apps/native storybook-generate`) and gitignored — never edit it.
+- The husky `pre-commit` hook (`.husky/pre-commit`) runs `bun run lint`, `bun run typecheck`,
+  and `bun run test:unit` before every commit. Hooks install via the `prepare` script on
+  `bun install`. It does not run the Storybook browser tests (they need Chromium) — run
+  `bun run test:storybook` yourself before pushing, since CI does. To bypass the hook in a
+  pinch, commit with `--no-verify`.
+- `storybook/native/.rnstorybook/storybook.requires.ts` is generated (by Metro or
+  `bun run --cwd storybook/native storybook-generate`) and gitignored — never edit it.
 - Test/story files are excluded from the published package and from the bob build; keep
   runtime code out of them.
 - The example app must stay on Expo SDK-pinned dependency versions (`bunx expo install ...`
-  from `apps/native` when adding native modules).
-
-## Scaffolder (`create/`)
-
-`create/` holds `create-react-native-library-template`, the npm package behind
-`bun create react-native-library-template`. It is **not** a workspace and is not managed by
-changesets: it has zero dependencies and is published manually. Its `prepack` script snapshots
-every tracked file of this repo (except `create/` itself) into `create/template/` (renaming
-`.gitignore` → `gitignore`, which the CLI reverses on scaffold); `postpack` deletes the
-snapshot. To release it: bump `create/package.json` version, then `cd create && npm publish`.
+  from `storybook/native` when adding native modules).

package/template/README.md

@@ -15,8 +15,8 @@ Template for building and publishing a React Native UI component library.
 
 ```
 packages/ui/        @template/ui — the library (published)
-apps/storybook/     Web Storybook + Storybook tests
-apps/native/        Expo app running Storybook React Native on device
+storybook/web/      Web Storybook + Storybook tests
+storybook/native/   Expo app running Storybook React Native on device
 ```
 
 ## Getting started

package/template/bun.lock

@@ -12,10 +12,30 @@
         "biome-one-liner-plugin": "1.3.2",
         "biome-react-best-practices-plugin": "1.1.0",
         "biome-typescript-best-practices-plugin": "1.0.0",
+        "husky": "^9.1.7",
         "typescript": "^6",
       },
     },
-    "apps/native": {
+    "packages/ui": {
+      "name": "@template/ui",
+      "version": "0.1.0",
+      "devDependencies": {
+        "@storybook/react": "^10.4.6",
+        "@testing-library/jest-dom": "^6.9.1",
+        "@testing-library/react": "^16.3.2",
+        "@types/react": "~19.1.10",
+        "jsdom": "^29.1.1",
+        "react": "19.1.0",
+        "react-dom": "19.1.0",
+        "react-native": "0.81.5",
+        "react-native-builder-bob": "^0.43.0",
+        "react-native-web": "0.21.2",
+        "storybook": "^10.4.6",
+        "typescript": "^6",
+        "vitest": "^4.1.10",
+      },
+    },
+    "storybook/native": {
       "name": "@template/example",
       "version": "0.0.0",
       "dependencies": {
@@ -46,7 +66,7 @@
         "typescript": "^6",
       },
     },
-    "apps/storybook": {
+    "storybook/web": {
       "name": "@template/storybook-web",
       "version": "0.0.0",
       "dependencies": {
@@ -71,25 +91,6 @@
         "vitest": "^4.1.10",
       },
     },
-    "packages/ui": {
-      "name": "@template/ui",
-      "version": "0.1.0",
-      "devDependencies": {
-        "@storybook/react": "^10.4.6",
-        "@testing-library/jest-dom": "^6.9.1",
-        "@testing-library/react": "^16.3.2",
-        "@types/react": "~19.1.10",
-        "jsdom": "^29.1.1",
-        "react": "19.1.0",
-        "react-dom": "19.1.0",
-        "react-native": "0.81.5",
-        "react-native-builder-bob": "^0.43.0",
-        "react-native-web": "0.21.2",
-        "storybook": "^10.4.6",
-        "typescript": "^6",
-        "vitest": "^4.1.10",
-      },
-    },
   },
   "packages": {
     "@0no-co/graphql.web": ["@0no-co/graphql.web@1.3.2", "", { "peerDependencies": { "graphql": "^14.0.0 || ^15.0.0 || ^16.0.0" }, "optionalPeers": ["graphql"] }, "sha512-Q1+pRlLhE31GOY/2c9BAEnFTNxO7Awtc6fhhEDlxyCBQ2N0IhD32cPVvPChrK9mwBNSgRdW/sF1kd2e0ojHj1Q=="],
@@ -794,9 +795,9 @@
 
     "@storybook/react-vite": ["@storybook/react-vite@10.4.6", "", { "dependencies": { "@joshwooding/vite-plugin-react-docgen-typescript": "^0.7.0", "@rollup/pluginutils": "^5.0.2", "@storybook/builder-vite": "10.4.6", "@storybook/react": "10.4.6", "empathic": "^2.0.0", "magic-string": "^0.30.0", "react-docgen": "^8.0.0", "resolve": "^1.22.8", "tsconfig-paths": "^4.2.0" }, "peerDependencies": { "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "storybook": "^10.4.6", "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0" } }, "sha512-0arEQtybqGYXHbXpTot+Wv9YtG+V5Vp43QayXavPKQ20M8mpEzhyCPKd0EhqMGSC1Z1UEt0hm365WUBhI9LfKA=="],
 
-    "@template/example": ["@template/example@workspace:apps/native"],
+    "@template/example": ["@template/example@workspace:storybook/native"],
 
-    "@template/storybook-web": ["@template/storybook-web@workspace:apps/storybook"],
+    "@template/storybook-web": ["@template/storybook-web@workspace:storybook/web"],
 
     "@template/ui": ["@template/ui@workspace:packages/ui"],
 
@@ -1268,6 +1269,8 @@
 
     "human-id": ["human-id@4.2.0", "", { "bin": { "human-id": "dist/cli.js" } }, "sha512-K3GbkIWqyvvlpfhBPlbEvD97TtqBpAYA4kt+cn2lD2x2HuohzZCibcA2nOlnJT6exqvJLggoB5nv2dNf192nEA=="],
 
+    "husky": ["husky@9.1.7", "", { "bin": { "husky": "bin.js" } }, "sha512-5gs5ytaNjBrh5Ow3zrvdUUY+0VxIuWVL4i9irt6friV+BqdCfmV11CQTWMiBYWHbXhco+J1kHfTOUkePhCDvMA=="],
+
     "hyphenate-style-name": ["hyphenate-style-name@1.1.0", "", {}, "sha512-WDC/ui2VVRrz3jOVi+XtjqkDjiVjTtFaAGiW37k6b+ohyQ5wYDOGkvCZa8+H0nx3gyvv0+BST9xuOgIyGQ00gw=="],
 
     "iconv-lite": ["iconv-lite@0.7.3", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-IKXpvIzjnC9XTAUbVBcMfGS0EPaIXtW6v+zr+RRp+hqULEpo0owZax6wyRwPOJbWbzjYspQwusTsfVr0ifh4uQ=="],

package/template/package.json

@@ -4,30 +4,32 @@
   "private": true,
   "workspaces": [
     "packages/*",
-    "apps/*"
+    "storybook/*"
   ],
   "scripts": {
     "build": "bun run --cwd packages/ui build",
-    "typecheck": "bun run --cwd packages/ui typecheck && bun run --cwd apps/storybook typecheck && bun run --cwd apps/native typecheck",
+    "typecheck": "bun run --cwd packages/ui typecheck && bun run --cwd storybook/web typecheck && bun run --cwd storybook/native typecheck",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "test": "bun run test:unit && bun run test:storybook",
     "test:unit": "bun run --cwd packages/ui test",
-    "test:storybook": "bun run --cwd apps/storybook test",
-    "storybook": "bun run --cwd apps/storybook storybook",
-    "storybook:native": "bun run --cwd apps/native start",
+    "test:storybook": "bun run --cwd storybook/web test",
+    "storybook": "bun run --cwd storybook/web storybook",
+    "storybook:native": "bun run --cwd storybook/native start",
     "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "bun run build && changeset publish"
+    "version-packages": "node scripts/version-packages.mjs",
+    "release": "bun run build && changeset publish",
+    "prepare": "husky"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.3",
     "@changesets/cli": "^2.31.0",
     "@iv-stpn/biome-config": "1.2.10",
-    "biome-one-liner-plugin": "1.3.2",
     "biome-drizzle-best-practices-plugin": "2.0.0",
+    "biome-one-liner-plugin": "1.3.2",
     "biome-react-best-practices-plugin": "1.1.0",
     "biome-typescript-best-practices-plugin": "1.0.0",
+    "husky": "^9.1.7",
     "typescript": "^6"
   }
 }

package/template/packages/ui/CHANGELOG.md

@@ -0,0 +1,34 @@
+# @template/ui
+
+## 0.1.5
+
+### Patch Changes
+
+- 92189ad: Add custom `version-packages` script that bumps the scaffolder version whenever changesets are consumed, so the template repo's release workflow republishes `create-react-native-library-template` alongside library changes. Update AGENTS.md to reflect the flow: only the scaffolder publishes from the template repo; `@template/ui` stays private. No runtime changes to the published package.
+
+## 0.1.4
+
+### Patch Changes
+
+- 2618470: Mark `@template/ui` as `private` so the release workflow no longer tries to publish the placeholder `@template` scope to npm (which 404s). Changesets still versions it and writes its changelog; the template only publishes the `create/` scaffolder. Scaffolded projects publish their library normally once the `@template/*` packages are renamed to your own npm scope and the `NPM_TOKEN` repository secret is set.
+- 4424a60: Remove the `private` flag from `@template/ui` so the release workflow publishes it to npm (the flag was preventing `changeset publish` from touching it). The scaffolder no longer strips it — scaffolded projects get a publishable library by default, which publishes once the scope is renamed and `NPM_TOKEN` is set.
+
+## 0.1.3
+
+### Patch Changes
+
+- a6ba45e: Mark `@template/ui` as `private` so the release workflow no longer tries to publish the placeholder `@template` scope to npm (which 404s). Changesets still versions it and writes its changelog; the template only publishes the `create/` scaffolder. Scaffolded projects that want to publish their library should rename the `@template/*` packages to their own npm scope, remove `"private": true` from `packages/ui/package.json`, and set the `NPM_TOKEN` repository secret.
+- f8a35ba: Add live-demo and npm badges plus a hosted-Storybook/scaffolder description to the repo `README.md`, and wrap those repo-only sections in `template-exclude` markers so scaffolded projects get a clean README without the template's own demo links and package badges. No runtime changes to the published package.
+
+## 0.1.2
+
+### Patch Changes
+
+- 6c594db: Add a husky `pre-commit` hook that runs lint, typecheck, and unit tests before every commit. Hooks install via a `prepare` script on `bun install`, and the setup is included in scaffolded projects (`bun create react-native-library-template`). The scaffolder's "Next steps" now runs `git init` before `bun install` so the hooks install on the first install. No runtime changes to the published package.
+
+## 0.1.1
+
+### Patch Changes
+
+- f77680d: Repo housekeeping: Storybook workspaces moved from `apps/` to `storybook/` (`storybook/web`, `storybook/native`), the web Storybook demo now deploys to GitHub Pages from `main`, and the contributor guide documents the exports-map convention (per-subpath `exports` in `package.json`, no barrel files). No runtime changes to the published package.
+- 98fd966: Remove `.tsx` extensions from relative imports in test and story files — they made `tsc --noEmit` fail with TS5097 since `allowImportingTsExtensions` is not enabled.

package/template/packages/ui/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@template/ui",
-  "version": "0.1.0",
+  "version": "0.1.5",
+  "private": true,
   "description": "Reusable React Native UI component library",
   "license": "MIT",
   "repository": {

package/template/scripts/version-packages.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+// Run changeset version
+execFileSync('bun', ['run', 'changeset', 'version'], { cwd: root, stdio: 'inherit' });
+
+// Bump the scaffolder version when changesets are consumed. This is a template repo;
+// the scaffolder must republish when template files change. Always bump it: if no changesets
+// existed, the version PR doesn't open and this doesn't run; if changesets exist, they're
+// for template changes and the scaffolder should ship alongside.
+const createPackagePath = resolve(root, 'create/package.json');
+const createPackage = JSON.parse(readFileSync(createPackagePath, 'utf8'));
+const [major, minor, patch] = createPackage.version.split('.').map(Number);
+createPackage.version = `${major}.${minor}.${patch + 1}`;
+writeFileSync(createPackagePath, `${JSON.stringify(createPackage, null, 2)}\n`);
+console.log(`Bumped create-react-native-library-template to ${createPackage.version}`);