Installation - Uniwind

Prerequisites

Before installing Uniwind Pro, ensure you have an active Uniwind Pro license.

New to Uniwind?

If you’re starting from scratch, follow the Quickstart guide first to set up Tailwind, Metro, and your project structure.

Install Dependencies

Add Uniwind Pro to your package.json dependencies manually:

package.json

{
  "dependencies": {
    "uniwind": "npm:uniwind-pro@latest"
  }
}

Then install the required peer dependencies:

bun
npm
yarn
pnpm

bun add react-native-nitro-modules react-native-reanimated react-native-worklets

npm install react-native-nitro-modules react-native-reanimated react-native-worklets

yarn add react-native-nitro-modules react-native-reanimated react-native-worklets

pnpm add react-native-nitro-modules react-native-reanimated react-native-worklets

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

Check the Compatibility page for supported React Native, Expo, and Nitro Modules versions.

Authenticate with GitHub

Run the CLI to authenticate:

bunx uniwind-pro

npx uniwind-pro

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”:

A browser tab will automatically open
Sign in with your GitHub account
Authorize the application
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

Your authentication session is valid for 180 days. After expiration, you’ll need to re-authenticate.

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.

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

Configure Babel

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

babel.config.js

module.exports = {
  // your presets and other configs
  plugins: [
    // other plugins
    'react-native-worklets/plugin',   
  ],
};

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

If you’re already using Reanimated, you may already have react-native-reanimated/worklets in your config.

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.

bun
yarn (v2+)
pnpm
npm

Bun blocks postinstall scripts by default. To allow the Uniwind postinstall script, add to your package.json:

package.json

{
    "trustedDependencies": ["uniwind"]
}

Add to your .yarnrc.yml:

.yarnrc.yml

packageExtensions:
  uniwind@*:
    scripts:
      postinstall: node scripts/postinstall.js

Or enable scripts globally (less secure):

.yarnrc.yml

enableScripts: true

Add to your .npmrc or run with the flag:

.npmrc

# Allow scripts for specific packages
enable-pre-post-scripts=true

Or approve the package:

pnpm config set enable-pre-post-scripts true

npm runs postinstall scripts by default. If you’ve disabled them with ignore-scripts=true, either remove that setting or run:

npm rebuild uniwind

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

Rebuild Your App

After installation, rebuild your native app:

Expo
Bare React Native

npx expo prebuild --clean

Then run your app:

npx expo run:ios
# or
npx expo run:android

For iOS, install pods:

cd ios && pod install && cd ..

Then run your app:

npx react-native run-ios
# or
npx react-native run-android

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.

Verify Installation

After rebuilding, verify that Uniwind Pro is working:

Check that your app starts without errors
Try using a Pro-only feature like Theme Transitions
Verify the CLI shows your license status:

bunx uniwind-pro

npx uniwind-pro

You should see your username and session validity.

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.

Troubleshooting

Installation fails with permission errors

Try running the CLI with elevated permissions or check that your package manager has write access to node_modules.

Postinstall script doesn't run

See the Whitelisting Postinstall Scripts section above. Most issues are caused by package managers blocking scripts.

Native module not found errors

Ensure you’ve rebuilt the native app after installation. Delete ios/build and android/build folders, then rebuild.

Authentication expired

Run uniwind-pro again and select “Login with Github” to re-authenticate. Sessions are valid for 180 days.

Download limit reached

Each license type has monthly download limits. Check your dashboard for current usage. Limits reset at the start of each month.

Still having issues?

Open an issue on GitHub and we’ll help you out. Pro users receive priority support.

​Prerequisites

New to Uniwind?

​Install Dependencies

​Authenticate with GitHub

​Install Uniwind Pro Package

​Configure Babel

​Whitelisting Postinstall Scripts

​Rebuild Your App

​Verify Installation

​Troubleshooting

Still having issues?

Prerequisites

Install Dependencies

Authenticate with GitHub

Install Uniwind Pro Package

Configure Babel

Whitelisting Postinstall Scripts

Rebuild Your App

Verify Installation

Troubleshooting