# @kivora/init assistant

One command to configure Kivora in Next.js or React Native.

## Configure your project with one command

@kivora/init is the official setup assistant. Run the command inside an existing application's directory, alongside its package.json. It detects Next.js or React Native and proposes the required files and dependencies. It does not create an application or install or migrate the framework.

Use npx @kivora/init. npm install @kivora/init only adds the package to your dependencies; it does not run setup. You do not need to keep the assistant as an application dependency.

- [@kivora/init on npm](https://www.npmjs.com/package/@kivora/init)


```bash
npx @kivora/init
```


## Requirements and platforms

This guide covers @kivora/init 0.1.1. It requires Node.js 20.19 or later in addition to framework requirements. It detects npm, pnpm, Yarn or Bun from packageManager and lockfiles, including those in a parent workspace.

Next.js: version 13+, React and React DOM 18+, Tailwind >=4.1 <5. The assistant adds Tailwind and PostCSS if missing; it does not migrate Tailwind 3. Manual web installation can use compiled CSS without Tailwind.

React Native: Community CLI >=0.85.3 <0.86, React >=19.2 <20, NativeWind >=4.2.6 <5, Reanimated >=4.3.0 <4.4, Worklets >=0.8.3 <0.9 and Tailwind >=3.4.17 <4. Babel preset and Metro config must be from the 0.85 series.

There is no React/Vite option and it does not migrate Expo projects. If both frameworks or neither are detected, it asks you to choose; that choice does not turn a React web project into Next.js.

- [React web without Next.js: manual installation](https://kivora.pro/docs/instalacion-react)

- [Set up React Native](https://kivora.pro/docs/instalacion-react-native)

## Review the plan before applying it

--dry-run shows current and proposed content without writing files or installing packages. In a normal run, the assistant validates the plan and asks for confirmation before writing. It preserves declared versions and installs only missing dependencies.


```bash
npx @kivora/init --dry-run

# Aplicar con confirmación interactiva
npx @kivora/init
```


## Assistant options

- --cwd: application directory.

- --framework nextjs|native: framework already installed in the project.

- --dry-run: preview without changes.

- --skip-install: write configuration and show pending installation commands.

- --yes: accept the plan without confirmation; use deliberately in automation.

- --package-manager npm|pnpm|yarn|bun: choose a manager if none is defined. Does not replace an existing manager.


```bash
npx @kivora/init --help
npx @kivora/init --cwd ./apps/web --framework nextjs --dry-run
npx @kivora/init --framework native --skip-install

# Automatización: aplica el plan sin confirmación interactiva
npx @kivora/init --cwd ./apps/web --framework nextjs --yes
```


## What it configures

- Next.js: adds @kivora/nextjs, Tailwind and PostCSS if missing; configures transpilePackages and the PostCSS plugin; generates provider and CSS files and connects them to App Router or Pages Router.

- React Native: adds @kivora/native and native dependencies, configures Babel, Metro and Tailwind, and integrates gesture, safe area, keyboard and Kivora providers with their color variables.

- On Android it adds POST_NOTIFICATIONS when a manifest exists. It does not run native builds or change Gradle, Podfile or image assets.

## Compatibility and recovery

Dynamic configurations with functions, spreads or unrecognized options may require manual integration. Conflicting package managers or incompatible version ranges stop the plan before writing. Do not force another version without reviewing compatibility.

The assistant stores copies in .kivora/backups/<id>/ and a manifest.json mapping each file to its backup. Keep backups until you review the integration and do not publish them. If the package manager fails, it restores files and lockfiles, but node_modules changes and script side effects are not a reversible transaction.

After setup, review styles and run your application's checks. On native, install pods using your project workflow, restart Metro and rebuild. The installer's README states that its iOS integration has not been validated.

- [Assistant README and troubleshooting](https://www.npmjs.com/package/@kivora/init)

Source: https://kivora.pro/docs/inicializador