Configuration reference

npx react-thaizip init writes thaizip.config.json at the project root. The add command reads it to locate component and shared-file destinations.

v4 shape

This example shows every v4 field for a project without a supported shadcn/ui configuration. Paths and the recorded CLI version depend on your project.

{
  "typescript": true,
  "componentDir": "app/components",
  "libDir": "lib",
  "hooksDir": "hooks",
  "packageManager": "npm",
  "tailwind": {
    "version": 4,
    "css": "app/globals.css"
  },
  "style": "vanilla",
  "shadcnBase": "",
  "shadcnUiAlias": "",
  "shadcnUiDir": "",
  "registryVersion": "0.3.7"
}

Field	Accepted value	Meaning
`typescript`	`true` or `false`	Auto-detected by `init` from the presence of `tsconfig.json` (no prompt). Determines whether `add` writes `.tsx`/`.ts` output as authored (`true`) or strips TypeScript syntax and writes `.jsx`/`.js` output instead (`false`).
`componentDir`	non-empty string	Component destination relative to the project root.
`libDir`	non-empty string	Destination for `utils.ts`; `init` defaults to `lib`.
`hooksDir`	non-empty string	Destination for shared hooks; defaults to `hooks`.
`packageManager`	`npm`, `yarn`, `pnpm`, `bun`	Package manager used by `add` for dependency installation.
`tailwind.version`	`3` or `4`	Detected Tailwind major version.
`tailwind.css`	string	Project-relative global CSS path, or `""` when no file was found.
`style`	`vanilla` or `shadcn`	Selects the authored Tailwind/Base UI templates or templates composed from the project's shadcn/ui primitives. Auto-detected by `init`.
`shadcnBase`	`""`, `base`, `radix`, or `aria`	`""` with `vanilla`; otherwise the component library behind the project's shadcn/ui primitives.
`shadcnUiAlias`	string	Import prefix from `components.json` `aliases.ui`; `""` with `vanilla`.
`shadcnUiDir`	string	Project-relative directory resolved from that alias; `""` with `vanilla`.
`registryVersion`	non-empty string	CLI version recorded the last time files were written; registry metadata, not the `thaizip` dependency version.

Every path is resolved from the working directory where the CLI runs. Run init and add from the same project root that contains the config file.

registryVersion is more than bookkeeping: add uses it to detect stale protected lib/hook files. When add skips one of those files because it already exists (protected), and the recorded registryVersion is older than the running CLI's own version, it prints a warning that the file may be stale along with the exact command to refresh it, for example npx react-thaizip add utils --overwrite. Whenever add actually writes at least one file — component, lib, or hook — it automatically bumps registryVersion in thaizip.config.json to the running CLI's version.

Component-style detection

init reads components.json when present. A style beginning with base-, radix-, or aria- selects the corresponding shadcn/ui template; legacy default and new-york select Radix. An absent or unrecognized style selects vanilla. For a recognized shadcn/ui project, add installs any missing UI primitives through the shadcn CLI. Vanilla interactive components use Base UI directly. ThaiAddressDisplay needs no UI primitives.

The selected style and shadcnBase are saved in the config. To change them after init, edit the config consistently and rerun add with --overwrite only after reviewing the files it would replace.

Project-structure detection

init chooses the initial componentDir in this order, checking from the project root:

Condition	Component directory
`app/` exists	`app/components/`
`app/` does not exist and `pages/` exists	`components/`
Neither exists	`src/components/`

If both app/ and pages/ exist, app/components/ wins. Without --yes, you can change the detected destination at the prompt before the config is written.

Package-manager detection

The CLI uses the first lockfile found in this order:

bun.lock or bun.lockb → bun
pnpm-lock.yaml → pnpm
yarn.lock → yarn
package-lock.json → npm
No recognized lockfile → npm

Tailwind detection

Tailwind is a prerequisite; init does not install it. Detection proceeds in this order:

Look for @import "tailwindcss" or its single-quoted form in a known global stylesheet. A match means Tailwind v4 with that CSS path.
If the tailwindcss dependency declares major version 4 or newer, use v4 and store tailwind.css as "" when no stylesheet was found.
Look for tailwind.config.ts, .js, .cjs, or .mjs. A match means v3; the CLI then looks for a known global stylesheet containing @tailwind.
If the dependency declares major version 3, use v3 and store an empty CSS path when no stylesheet was found.
If none match, init stops and points you to Tailwind installation instructions.

The global CSS candidates, in order, are app/globals.css, src/app/globals.css, styles/globals.css, src/styles/globals.css, src/index.css, src/App.css, and app/global.css.

File writes and import paths

Component templates are authored with @/lib/* and @/hooks/* imports so they can typecheck in the registry. Whenever add copies a component file, including an overwrite, it rewrites those specifiers to extensionless relative paths from componentDir to the configured libDir and hooksDir.

For example, with componentDir set to app/components, libDir to lib, and hooksDir to hooks, imports point out of app/components to those two directories. The target project does not need an @ alias for generated component imports.

Existing lib and hook files are protected by default, even with --yes, and are replaced only with an explicit --overwrite. Existing component files are skipped by default and replaced only after confirmation or with --overwrite. Import rewriting therefore runs only when a component is actually copied.

Legacy configuration

When add reads a recognized v1, v2, or v3 config, it migrates it in place to v4. The v1 migration fills in libDir, hooksDir, and Tailwind metadata (using Tailwind v4 with an empty CSS path if detection fails), while preserving typescript: false when present. v1/v2 configs become vanilla; an existing v3 shadcn config gains shadcnBase: "base", since v3 only recognized Base UI-backed shadcn styles. Migration does not re-detect the project's current shadcn style. If the resulting config is invalid, rerun npx react-thaizip init to regenerate it.

If paths or metadata do not match the project, follow the recovery steps in Troubleshooting.