> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uniwind.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install Uniwind Pro in your React Native project

## Prerequisites

Before installing Uniwind Pro, ensure you have an active Uniwind Pro [license](/pro/get-license).

<Card title="New to Uniwind?" icon="rocket" href="/quickstart">
  If you're starting from scratch, follow the Quickstart guide first to set up Tailwind, Metro, and your project structure.
</Card>

## Install Dependencies

Add Uniwind Pro to your `package.json` dependencies manually:

```json package.json theme={null}
{
  "dependencies": {
    "uniwind": "npm:uniwind-pro@latest"
  }
}
```

Then install the required peer dependencies:

<Tabs>
  <Tab title="bun">
    ```bash theme={null}
    bun add react-native-nitro-modules react-native-reanimated react-native-worklets
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install react-native-nitro-modules react-native-reanimated react-native-worklets
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add react-native-nitro-modules react-native-reanimated react-native-worklets
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add react-native-nitro-modules react-native-reanimated react-native-worklets
    ```
  </Tab>
</Tabs>

<Warning>
  The first installation attempt will fail because you are not yet authorized. This is expected - continue with the authentication step below.
</Warning>

<Info>
  Check the [Compatibility](/pro/compatibility) page for supported React Native, Expo, and Nitro Modules versions.
</Info>

## Authenticate with GitHub

Run the CLI to authenticate:

<Tabs>
  <Tab title="bun">
    ```bash theme={null}
    bunx uniwind-pro
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npx uniwind-pro
    ```
  </Tab>
</Tabs>

You'll see the following menu:

```
  _   _       _          _           _   ____
 | | | |_ __ (_)_      _(_)_ __   __| | |  _ \ _ __ ___
 | | | | '_ \| \ \ /\ / / | '_ \ / _` | | |_) | '__/ _ \
 | |_| | | | | |\ V  V /| | | | | (_| | |  __/| | | (_) |
  \___/|_| |_|_| \_/\_/ |_|_| |_|\__,d| |_|   |_|  \___/


? What would you like to do?
❯ Login with Github
  Buy Uniwind Pro
  Exit
```

**Select "Login with Github":**

1. A browser tab will automatically open
2. Sign in with your GitHub account
3. Authorize the application
4. Wait for the success message: **"You can close this tab and return to the terminal."**

After successful authentication, you'll see:

```
? Hello @your-username, what would you like to do?
  Your session is valid for the next 179 days
────────────────────────────────────────────
❯ Manage your account
  Install Uniwind Pro
  Logout
  Exit
```

<Info>
  Your authentication session is valid for 180 days. After expiration, you'll need to re-authenticate.
</Info>

## Install Uniwind Pro Package

From the CLI menu, select **"Install Uniwind Pro"**:

```
? Hello @your-username, what would you like to do?
  Your session is valid for the next 179 days
────────────────────────────────────────────
  Manage your account
❯ Install Uniwind Pro
  Logout
  Exit
```

The CLI will automatically fetch and install the Uniwind Pro package from the CDN.

<Tip>
  The installation process automatically handles version compatibility, ensuring you get the correct Pro version for your CLI.
</Tip>

## Configure Babel

Add the `react-native-worklets/plugin` to your `babel.config.js`:

```js babel.config.js theme={null}
module.exports = {
  // your presets and other configs
  plugins: [
    // other plugins
    'react-native-worklets/plugin',   // [!code ++]
  ],
};
```

<Info>
  The `react-native-worklets/plugin` must be listed in the plugins array to work correctly.
</Info>

<Tip>
  If you're already using Reanimated, you may already have `react-native-reanimated/worklets` in your config.
</Tip>

## Whitelisting Postinstall Scripts

Some package managers block postinstall scripts by default for security reasons. If the Uniwind Pro installation fails or the package doesn't work correctly, you may need to whitelist the postinstall script.

<Tabs>
  <Tab title="bun">
    Bun blocks postinstall scripts by default. To allow the Uniwind postinstall script, add to your `package.json`:

    ```json package.json theme={null}
    {
        "trustedDependencies": ["uniwind"]
    }
    ```
  </Tab>

  <Tab title="yarn (v2+)">
    Add to your `.yarnrc.yml`:

    ```yaml .yarnrc.yml theme={null}
    packageExtensions:
      uniwind@*:
        scripts:
          postinstall: node scripts/postinstall.js
    ```

    Or enable scripts globally (less secure):

    ```yaml .yarnrc.yml theme={null}
    enableScripts: true
    ```
  </Tab>

  <Tab title="pnpm">
    Add to your `.npmrc` or run with the flag:

    ```ini .npmrc theme={null}
    # Allow scripts for specific packages
    enable-pre-post-scripts=true
    ```

    Or approve the package:

    ```bash theme={null}
    pnpm config set enable-pre-post-scripts true
    ```
  </Tab>

  <Tab title="npm">
    npm runs postinstall scripts by default. If you've disabled them with `ignore-scripts=true`, either remove that setting or run:

    ```bash theme={null}
    npm rebuild uniwind
    ```
  </Tab>
</Tabs>

<Warning>
  If postinstall scripts don't run, Uniwind Pro may fail to initialize correctly. You'll see errors about missing native modules or configuration.
</Warning>

## Rebuild Your App

After installation, rebuild your native app:

<Tabs>
  <Tab title="Expo">
    ```bash theme={null}
    npx expo prebuild --clean
    ```

    Then run your app:

    ```bash theme={null}
    npx expo run:ios
    # or
    npx expo run:android
    ```
  </Tab>

  <Tab title="Bare React Native">
    For iOS, install pods:

    ```bash theme={null}
    cd ios && pod install && cd ..
    ```

    Then run your app:

    ```bash theme={null}
    npx react-native run-ios
    # or
    npx react-native run-android
    ```
  </Tab>
</Tabs>

<Warning>
  A native rebuild is required for Uniwind Pro to work correctly. Simply restarting Metro is not enough. Uniwind Pro doesn't work with Expo Go.
</Warning>

## Verify Installation

After rebuilding, verify that Uniwind Pro is working:

1. Check that your app starts without errors
2. Try using a Pro-only feature like [Theme Transitions](/pro/theme-transitions)
3. Verify the CLI shows your license status:

<Tabs>
  <Tab title="bun">
    ```bash theme={null}
    bunx uniwind-pro
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npx uniwind-pro
    ```
  </Tab>
</Tabs>

You should see your username and session validity.

<Tip>
  You can verify that the CLI stub was replaced with the actual Uniwind Pro code by checking if `node_modules/uniwind` contains native modules (`.cpp`, `.mm` files) instead of just the CLI placeholder.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Installation fails with permission errors">
    Try running the CLI with elevated permissions or check that your package manager has write access to `node_modules`.
  </Accordion>

  <Accordion title="Postinstall script doesn't run">
    See the [Whitelisting Postinstall Scripts](#whitelisting-postinstall-scripts) section above. Most issues are caused by package managers blocking scripts.
  </Accordion>

  <Accordion title="Native module not found errors">
    Ensure you've rebuilt the native app after installation. Delete `ios/build` and `android/build` folders, then rebuild.
  </Accordion>

  <Accordion title="Authentication expired">
    Run `uniwind-pro` again and select "Login with Github" to re-authenticate. Sessions are valid for 180 days.
  </Accordion>

  <Accordion title="Download limit reached">
    Each license type has monthly download limits. Check your [dashboard](https://uniwind.dev/dashboard) for current usage. Limits reset at the start of each month.
  </Accordion>
</AccordionGroup>

<Card title="Still having issues?" icon="github" href="https://github.com/uni-stack/uniwind/issues">
  Open an issue on GitHub and we'll help you out. Pro users receive priority support.
</Card>