create-uniform-search

Scaffold a complete Uniform Search faceted-search experience into an existing Next.js App Router project that already uses the Uniform SDK. It copies the search React components + helpers, drops in the Uniform CLI package file, optionally pushes the Uniform component definitions, and can install the companion Claude Code skill.

Usage

Run it from your project root:

npm create uniform-search@latest
# or
npx create-uniform-search
# or
pnpm create uniform-search

You'll be asked:

1. Install the Uniform Search components? — yes/no. Yes copies the components + helpers + search-components.json / uniformsearch.config.js.
2. Where to install the React components/helpers? — a folder you enter (defaults to the base your @/* import alias points to, e.g. . or src). The tool never assumes a location. Files land at <folder>/components/search, <folder>/lib/search, and <folder>/styles/search-theme.css; the search-components.json / uniformsearch.config.js artifacts always go to the project root (where the deploy runs).
3. Which locale? — the search-components.json package ships authored patterns/compositions in a single locale (en). Before writing it, the tool detects your project's default locale from the Uniform REST API (when UNIFORM_API_KEY + UNIFORM_PROJECT_ID are present) and rewrites the package to that locale, so the patterns render. If the API can't be reached (no creds, network, etc.) you're prompted for a locale code (default en). Pass --locale <code> to set it explicitly and skip detection.
4. Deploy the Uniform component definitions to your Uniform project now? — yes/no. This question is only shown when both UNIFORM_API_KEY and UNIFORM_PROJECT_ID are present in .env or .env.local (the CLI push authenticates with them). If either is missing, deploy is skipped and you're shown the command to run later.
5. Add the Claude Code skill? — installs .claude/skills/add-uniform-search if yes.

Non-interactive / CI

npx create-uniform-search --components --deploy --skill   # copy + deploy + install skill
npx create-uniform-search --components --no-deploy         # copy only
npx create-uniform-search --components --src-root src      # install components under ./src
npx create-uniform-search --components --locale en-US       # author the package in en-US (skip detection)
npx create-uniform-search --no-components                  # skip the components entirely
npx create-uniform-search --yes                            # safe defaults: components, no deploy, no skill
npx create-uniform-search --dry-run                        # show what would happen
npx create-uniform-search --dir ./apps/web --components    # target a specific directory

--deploy still requires both creds in .env / .env.local; if they're absent the deploy is skipped regardless of the flag.

Use --src-root <path> (alias --components-dir) to set the install folder non-interactively; when omitted in interactive mode you'll be prompted, and in non-interactive mode it falls back to the detected @/* alias base.

The bundled uniformsearch.config.js sets serialization.mode: 'create', so the push is additive — it only creates entities that don't already exist and never updates or deletes content in your Uniform project. (uniform sync push has no -m/--mode flag; the mode is configured in the file.)

Use --locale <code> to author search-components.json in a specific locale non-interactively and skip auto-detection. Without it, the CLI detects the project default locale via the Uniform REST API (needs the creds above) and otherwise falls back to en.

After scaffolding

• Register the search components in your component resolver (searchEngine, searchBox, searchList, searchPagination, searchSorting, searchTotalAmount, facetContainer, searchFacet). Map searchDemoPage to your existing page shell if you keep the demo page.
• Import styles/search-theme.css (the mono-* Tailwind theme tokens) from your global stylesheet.
• Install the runtime package if it isn't already: npm install @uniformdev/search.

Testing locally (without publishing)

Build first (this also syncs templates/):

pnpm --filter create-uniform-search build

Then pick one:

1. Run the built file directly (fastest iteration). From a scratch test project:

node /path/to/search-starter/packages/create-uniform-search/dist/index.js --dir . --components --dry-run

2. npm pack + run the tarball (closest to real npm create). This validates that dist/ and templates/ are actually included in the published artifact:

cd packages/create-uniform-search
npm pack                       # -> create-uniform-search-<version>.tgz
cd /path/to/scratch-project
npx /abs/path/create-uniform-search-<version>.tgz --components --no-deploy

3. npm link (global symlinked bin).

cd packages/create-uniform-search && npm link
cd /path/to/scratch-project && create-uniform-search --components --no-deploy
# undo later with: npm rm -g create-uniform-search

Make a throwaway target project to test against (App Router shape + an @/* alias):

mkdir -p /tmp/cus-scratch/app && cd /tmp/cus-scratch
echo '{"name":"scratch"}' > package.json
printf '{"compilerOptions":{"paths":{"@/*":["./*"]}}}' > tsconfig.json

Use --dry-run to preview, --components --no-deploy to copy without pushing, and --components --deploy only when the target's .env / .env.local has real UNIFORM_API_KEY / UNIFORM_PROJECT_ID (it will hit your Uniform project).

Maintenance

The scaffolding payload is not stored in this package's git history — templates/ is generated from the canonical Claude skill at .claude/skills/add-uniform-search/ by scripts/sync-templates.mjs (runs automatically on prebuild and prepublishOnly, or manually via pnpm --filter create-uniform-search sync).