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 application.

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:

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
d-----       03/09/2018     03:13                dist
d-----       03/09/2018     03:14                example
d-----       03/09/2018     03:13                node_modules
d-----       03/09/2018     03:13                src
-a----       03/09/2018     03:13             85 .gitignore
-a----       03/09/2018     03:13            411 CHANGELOG.md
-a----       03/09/2018     03:13           1070 LICENSE
-a----       03/09/2018     03:13         189463 package-lock.json
-a----       03/09/2018     03:13            719 package.json
-a----       03/09/2018     03:13            363 README.md

Let's take a look at each of these files and directories.

/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 application. 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 your 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.

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:

 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:

---

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

$ create-react-prototype