references/local-library.md
title: Add a Local Library to an Existing App impact: HIGH tags: react-native, library, create-react-native-library, local, autolinking, monorepo, expo
Skill: Add a Local Library to an Existing App
Scaffold a local library inside an existing React Native app with create-react-native-library.
When to Use
- Adding native functionality or UI components to an existing React Native app
Prerequisites
- An existing React Native app with
package.jsonat the root
Step-by-Step Instructions
Progress checklist:
- [ ] Create local library with CLI
- [ ] Verify symlink setup in node_modules
- [ ] Install dependencies to create symlink
- [ ] Import and use the library in the app
-
Run
npx create-react-native-library@latest --helpto check the latest available options. -
Choose the appropriate
--typebased on user's requirements:- Use
turbo-moduleornitro-modulefor exposing native APIs. - Use
fabric-viewornitro-viewfor rendering native UI components.
- Use
-
Choose the appropriate
--languagesbased on the--type:- Use
kotlin-objcfor Turbo Modules or Fabric Components. - Use
kotlin-swiftfor Nitro Modules or Nitro Views.
- Use
-
Run the
npx create-react-native-library@latestcommand with the--localflag from the root of the existing app to scaffold a local library under themodules/folder:cd MyApp # Scaffold a local Turbo Module inside the app repo npx create-react-native-library@latest awesome-library \ --local \ --no-interactive \ --yes \ --description "A brief description of the library" \ --type turbo-module \ --languages kotlin-objc -
Verify the local library is linked correctly in the app's
dependenciesinpackage.json:- If the app uses Yarn, the generated dependency entry in
package.jsonshould uselink:("react-native-awesome-library": "link:./modules/awesome-library") - If the app uses npm, the generated dependency entry in
package.jsonshould usefile:("react-native-awesome-library": "file:./modules/awesome-library") - For other package manager setups, refer to the package manager documentation on how to create symlink under
node_modulesthat points to the local library.
- If the app uses Yarn, the generated dependency entry in
-
Run
yarn installornpm installfrom the app root to create the symlink undernode_modulesthat points to the local library. -
For nitro modules or views, ensure
react-native-nitro-modulesdependency is added to the app'spackage.json. -
Import the library with its package name (e.g.
import { multiply } from 'react-native-awesome-library') in the app to use it.
Generated Project Structure
Typical generated layout:
MyApp/
package.json
modules/
awesome-library/
src/ TypeScript entry points
android/ Android native implementation
ios/ iOS native implementation
package.json Local package metadata
The local library is self contained under the modules/ folder and is symlinked into the app's node_modules/ for autolinking.
Common Pitfalls
- Not running the command from an app directory: Run from a React Native app directory that already contains
package.json. - Using incorrect combination of
--typeand--languages: Usekotlin-objcfor turbo modules and fabric views, and usekotlin-swiftfor nitro modules and nitro views.