Home

Welcome to the create-react-prototype wiki!

This wiki will be a (hopefully) comprehensive guide to this CLI.

The main goal of create-react-prototype is to make your life as a library author easier. It saves you from having to worry about how to compile, test and build your library and lets you focus on actually writing your library.

Getting started

Hint

Try out the help command if you ever get stuck. It displays all possible commands and their arguments.

The simplest way to create a new project is using the init command. It will create a new project in your current working directory. Make sure you are in the right one before running this!

$ create-react-prototype init

Please enter as much data in the following dialog as possible, as the generated files will assume that the data is valid.

You should now have the following file structure:

/package.json, /package-lock.json, /node_modules/

Your package files used by NPM. Refer to the NPM documentation for more details: https://docs.npmjs.com/files/package.json

/README.md

Your Readme file, add information about your library here.

/LICENSE

The license of your library. If you picked a fairly common license in the init command this file should have the license text auto generated. If not make sure to fill it in!

/CHANGELOG.md

Changelogs & adhering Semantic Versioning are really important for libraries. Your users need to know what changed, and if it's a breaking change. You'll either need to update your changelog manually or find a tool to generate it for you.

/.gitignore

We put some default contents into the gitignore. Feel free to edit it to your desire. Keep in mind though that build output and dependencies do not belong in the repository.

/src/

This directory is the heart of your library. It contains all source files. Every file in this directory will be compiled and written into the /dist/ folder, mapping the file structure 1:1.

You can optionally also provide a .d.ts file for every .js file if you want to provide TypeScript typings.

See the section about /dist for more details.

/dist/

The build output of your library. The content in this directory is generated by either the build or watch command.

Since the content of this directory is used to publish the library instead of the root directory it also contains a copy of your package.json along with some other files.

/example/

This can either be your playground to test your features, or a full fledged demo for your users.

Since it is a create-react-app you can find documentation about it here should you intend to do something advanced with it: https://github.com/facebook/create-react-app

Feel free to edit the example in order to be able to properly showcase your work.

One important thing to keep in mind is that the example uses the content of your /dist folder. For this reason it is important to run in your root directory npm run watch if you want live reloading features in the example.

/storybook/

The storybook is a place to showcase all components in your library.

You can write individual stories to show off the capabilities of a single component in isolation without having to write an entire app surrounding it.

The storybook uses @storybook/react. Take a look at its documentation here: https://storybook.js.org/basics/guide-react/

Hint

The storybook integration is still under active development. For this reason you still have to write config files for it and import all of your storybook components manually in /storybook/config/config.js. We are actively working on improving the storybook experience.

Hello World!

Let's see how fast we can get a "Hello World" on our screen. Now that we have set up our library run the following commands:

$ npm run watch
$ cd example
$ npm run start

After a second or two your browser should open and display a slightly modified create-react-app.

Let's edit /src/index.js:

-export default () => (<span>Welcome to <em>my-library</em>!</span>);
+export default () => (<span>Welcome to <em>my-awesome-library</em>, powered by create-react-prototype!</span>);

This causes the example to reload:

Let's add a new component to our library:

// src/Time.js
import * as React from "react";

class Time extends React.PureComponent {
  render() {
    return (<span>It is {this.props.date.toLocaleTimeString()}.</span>);
  }
}

export default Time;

Let's import and display it in the example:

// example/src/App.js
 import MyComponent from "my-library";
+import Time from "my-library/Time";
 import './App.css';
...
 </header>
+ <h2><Time date={new Date()} /></h2>
 <p className="App-intro">

And we can instantly see the new component in the example:

Command Reference

Hint

You can open the CLI without any arguments to enter a REPL mode:

$ create-react-prototype

init

This command performs the first time setup of your library.

See the Getting Started section for more details.

Arguments:

• -D --dependency <dependency> - Decides on how to add create-react-prototype as a dependency.
  • npm (default) - Adds the create-react-prototype NPM package as a devDependency. (You can also use npm@^1.2.0 to e.g. install version ^1.2.0.)
  • retain - Your current package.json setting will be retained.
  • local - Adds create-react-prototype by determining its local installation path. (Not recommended, only useful if you want to develop on create-react-prototype)
  • tgz - Packs the create-react-prototype into a tarball and installs the tarball. May require sudo. (Not recommended, only useful if you want to develop on create-react-prototype and test a npm release)
  • none - create-react-prototype will not be added as a devDependency. (Not recommended, this would require all contributors to have create-react-prototype installed globally)
• -P --packageManager - Specify the package manager to use for your project.
  • npm (default) - Use NPM. https://github.com/npm/cli
  • yarn - Use Yarn. https://yarnpkg.com/en/ (Hint: Yarn is currently unsupported - See details: https://github.com/PatrickSachs/create-react-prototype/issues/5)
• -Y --yes - Skip the package.json creation questions. (Not recommended, as we use some answers provided in it to generate files)
• --noExample - Opt out of creating an example project.
• --noStorybook - Opt out of creating a storybook project.
• --debug - Activates debug output for this command.

build

This builds your library in production mode. Production mode makes various optimizations to the code that improves user experience but will make it harder to debug. See the watch command for development usage.

ESLint is run over each file to catch as many problems as possible early on. The ESLint configuration uses the same settings as the ones used by create-react-app to ensure a consistent coding experience between the example and your library.

The build output is placed under /dist, and mirrors your file structure 1:1. Some additional files like your package.json, README and TypeScript definitions are also copied.

Arguments:

• --debug - Activates debug output for this command.

watch

Similar to build, but compiles in development mode. Furthermore, the CLI stays active and listens to file system changes. Should anything change, the file or directory will be recompiled & relinted.

If you get a ENOSPC error, but you actually have free disk space - it means that your OS watcher limit is too low for the amount of files in your library.

Follow this description to increase the limit: https://confluence.jetbrains.com/display/IDEADEV/Inotify+Watches+Limit

Arguments:

• --debug - Activates debug output for this command.

test

Runs all unit tests in your project. Unit tests are powered by Jest. A unit test can be created by creating files ending with .test.js in the /src directory.

See the Jest documentation for more details: https://jestjs.io/

Arguments:

• -W --watch - Watches the tests for changes. (Only available if a git repository exists)
• -WA -watchAll - Watches the tests for changes. (Only available if no git repository exists)
• --debug - Activates debug output for this command.

publish

Releases your package on NPM. Builds beforehand.

Arguments:

• --debug - Activates debug output for this command.

pack

Creates a .tgz file in your library root with the identical contents of what would get published to npm. You can install this file in other projects using npm i /path/to/my-library.tgz to test it. Builds beforehand.

Arguments:

• --debug - Activates debug output for this command.

example/start

Starts your example in development mode(default port: 3000). Make sure to run the watch command of your library first.

example/build

Builds your example into a static build output you can deploy somewhere.

storybook/start

Starts your storybook in development mode(default port: 9001). Make sure to run the watch command of your library first.

storybook/build

Builds your storybook into a static build output you can deploy somewhere.