Nuns Playing Monopoly

    create-react-native-module

    0.20.2 • Public • Published

    create-react-native-module

    Tool to create a React Native library module or native view component, with a single command.

    GitHub license npm Mutation testing badge npm downloads total npm downloads GitHub watchers GitHub stars GitHub forks open bugs total open issues GitHub pull requests

    See below for command-line usage, example with no view, and example with an extremely simple native view.

    This tool based on react-native-create-library, with working example callbacks, optional native view, and more updates added by @brodybits (Christoper J. Brody aka Chris Brody) and other contributors.

    Support options

    General status

    • Minimum React Native version: 0.60 (outdated), 0.63 (recommended) - see issue #423
    • It is recommended to disable or remove Flipper on iOS in case of debug build issues - see issue #422
    • generated example app with symlink by default, has known issue with adding dependencies to the library root - see issue #308
    • Platform fork support
    • Out-of-tree platforms
      • Windows - no longer supported for reasons discussed in issues #23 and #43 (existing Windows C# template is kept in unsupported-platforms for now (at least) and further discussion would be welcome in a new issue on GitHub)
      • for future consideration: macOS (see issue #94)

    Why might you need this?

    If you are looking to create a native module for React Native, you need some native code for each platform you want to support and then some JavaScript code to bind it all together. Setting this up by yourself can be time-consuming.

    This is where this tool comes in. It creates a boilerplate with all current best practices in mind. Why not use react-native new-library? Unfortunately that command doesn't create an up-to-date library, requires an already initialized React Native project and only sets up the iOS side of things.

    Alternatives

    Outdated alternatives: see acknowledgements below

    Installation

    Package required to be installed globally if the recommended example app is generated:

    $ npm install -g yarn

    To install this package:

    $ npm install -g create-react-native-module

    Command-line usage

    Navigate into an empty directory to execute the command.

    $ create-react-native-module MyFancyLibrary

    This will create the folder MyFancyLibrary in which the library will be created in.

    Now install dependencies by running this command in the newly created library.

    $ npm install
    Usage: create-react-native-module [options] <name>
    
    Options:
    
      -V, --version                             output the version number
      --package-name <packageName>              The full package name to be used in package.json. Default: react-native-(name in param-case)
      --is-view                                 Generate the package as a very simple native view component. Status: EXPERIMENTAL, with limited testing.
      --object-class-name                       The name of the object class to be exported by both JavaScript and native code. Default: (name in PascalCase)
      --native-package-id <nativePackageId>     [Android] The native Java package identifier used for Android (Default: `com.reactlibrary`)
      --platforms <platforms>                   Platforms the library module will be created for - comma separated (Default: `ios,android`)
      --tvos-enabled                            Generate the module with tvOS build enabled (requires react-native-tvos fork, with minimum version of 0.60, and iOS platform to be enabled)
      --github-account <githubAccount>          The github account where the library module is hosted (Default: `github_account`)
      --author-name <authorName>                The author's name (Default: `Your Name`)
      --author-email <authorEmail>              The author's email (Default: `yourname@email.com`)
      --license <license>                       The license type (Default: `MIT`)
      --use-apple-networking                    [iOS] EXPERIMENTAL FEATURE NOT SUPPORTED: Use `AFNetworking` dependency as a sample in the podspec & use it from the iOS code - see issue #426
      --generate-example                        Generate an example project and add the library module to it with symlink by defult, with overwrite of example metro.config.js to add workaround for Metro symlink issue - requires Yarn to be installed globally
      --example-file-linkage                    DEPRECATED: do `yarn add file:../` instead of `yarn add link:../` in a generated example project, and add a postinstall workaround script, with no overwrite of example metro.config.js
      --example-name <exampleName>              Name for the example project (default: `example`)
      --example-react-native-template <...>     The React Native template used for the generated example project, for example: react-native-tvos or react-native-tvos@0.62.2-1 (requires --tvos-enabled option); react-native@0.62 (default: `react-native@latest`)
      --write-example-podfile                   [iOS] EXPERIMENTAL FEATURE NOT SUPPORTED: write (or overwrite) example ios/Podfile
      -h, --help                                output usage information

    Programmatic usage

    const createLibraryModule = require('create-react-native-module');
    
    createLibraryModule({
      name: 'MyFancyLibraryModule'
    }).then(() => {
      console.log('Oh yay! My library module has been created!');
    })

    Options

    {
      name: String, /* The name of the library (mandatory) */
      packageName: String, /* The full package name to be used in package.json. Default: react-native-(name in param-case) */
      isView: Boolean, /* Generate the package as a very simple native view component. Status: EXPERIMENTAL, with limited testing. (Default: false) */
      objectClassName: String, /* The name of the object class to be exported by both JavaScript and native code. Default: (name in PascalCase) */
      platforms: Array | String, /* Platforms the library will be created for. (Default: ['android', 'ios']) */
      nativePackageId: String, /* [Android] The native Java package identifier used for Android (Default: `com.reactlibrary`) */
      tvosEnabled: Boolean, /* Generate the module with tvOS build enabled (requires react-native-tvos fork, with minimum version of 0.60, and iOS platform to be enabled) */
      githubAccount: String, /* The github account where the library is hosted (Default: `github_account`) */
      authorName: String, /* The author's name (Default: `Your Name`) */
      authorEmail: String, /* The author's email (Default: `yourname@email.com`) */
      license: String, /* The license type of this library (Default: `MIT`) */
      useAppleNetworking: Boolean, /* [iOS] EXPERIMENTAL FEATURE NOT SUPPORTED: Use `AFNetworking` dependency as a sample in the podspec & use it from the iOS code - see issue #426 (Default: false) */
      generateExample: Boolean, /* Generate an example project and add the library module to it with symlink by defult, with overwrite of example metro.config.js to add workaround for Metro symlink issue - requires Yarn to be installed globally (Default: false) */
      exampleFileLinkage: Boolean, /* DEPRECATED: do `yarn add file:../` instead of `yarn add link:../` in a generated example project, and add a postinstall workaround script, with no overwrite of example metro.config.js (Default: false) */
      exampleName: String, /* Name for the example project (Default: `example`) */
      exampleReactNativeTemplate: String, /* The React Native template used for the generated example project, for example: react-native-tvos or react-native-tvos@0.62.2-1 (requires --tvos-enabled option); react-native@0.62 (Default: `react-native@latest`) */
      writeExamplePodfile: Boolean, /* [iOS] EXPERIMENTAL FEATURE NOT SUPPORTED: write (or overwrite) example ios/Podfile (Default: false) */
    }

    Examples

    Example module with no view

    Create the module with no view:

    create-react-native-module --package-identifier io.mylibrary --generate-example AliceHelper

    The module would be generated in the react-native-alice-helper subdirectory, and the example test app would be in react-native-alice-helper/example.

    Then go into the example app subdirectory:

    cd react-native-alice-helper/example

    Running the example app

    Recommended: Follow the instructions shown in the end of the console log output, which are more likely to be up-to-date.

    Extra notes:

    Within the example test app subdirectory:

    It is recommended to start the Metro Bundler manually (within react-native-alice-helper/example), which would run in the foreground:

    yarn start

    Otherwise, React Native will open its own window to run the Metro Bundler.

    To run on Android, do the following command (within react-native-alice-helper/example):

    yarn android

    for React Native 0.60: npx react-native run-android

    This assumes that the ANDROID_HOME environmental variable is set properly. Here is a sample command that does not make such an assumption on a mac:

    ANDROID_HOME=~/Library/Android/sdk npx react-native run-android

    For iOS:

    Extra installation step needed in case of clean checkout only:

    cd ios && pod install && cd ..

    Then to run on iOS:

    yarn ios

    for React Native 0.60: npx react-native run-ios

    or do the following command to open the iOS project in Xcode:

    open ios/example.xcodeproj

    Expected result

    The example app shows the following indications:

    • STATUS: native callback received
    • NATIVE CALLBACK MESSAGE with the number argument and string argument values that are received by the native module

    Example view module

    EXPERIMENTAL feature with limited testing

    Create the module with an extremely simple view:

    create-react-native-module --package-identifier io.mylibrary --is-view --generate-example CarolWidget

    The module would be generated in the react-native-carol-widget subdirectory, and the example test app would be in react-native-carol-widget/example.

    Then go into the example app subdirectory:

    cd react-native-carol-widget/example

    Running the view example app

    Recommended: Follow the instructions shown in the end of the console log output, which are more likely to be up-to-date.

    Some extra notes:

    Within the example test app subdirectory:

    It is recommended to start the Metro Bundler manually as described above (within react-native-carol-widget/example):

    yarn start

    To run on Android: do yarn android or npx react-native run-android as described for the other example above.

    To run on iOS (as described above):

    • in case of clean checkout only: do pod install in ios subdirectory
    • do yarn ios, npx react-native run-ios, or open ios/example.xcodeproj

    Expected result:

    • on Android: a check box that is checked (and cannot be changed)
    • on iOS: a label with 5 red asterisks

    Acknowledgements

    License

    MIT

    Install

    npm i create-react-native-module

    DownloadsWeekly Downloads

    302

    Version

    0.20.2

    License

    MIT

    Unpacked Size

    88.9 kB

    Total Files

    14

    Last publish

    Collaborators

    • brodybits