This project was bootstrapped with the NodeKit Command Line.

Below you will find some information on how to perform common tasks.
You can find the most recent version of this guide here.

Table of Contents

• Updating to New Releases
• Sending Feedback
• Folder Structure
• Available Scripts
  • npm start
  • npm test
  • npm run build
  • npm run eject
• Supported Language Features and Polyfills
• Syntax Highlighting in the Editor
• Displaying Lint Output in the Editor
• Changing the Page <title>
• Installing a Dependency
• Importing a Component
• Adding a Stylesheet
• Post-Processing CSS
• Adding a CSS Preprocessor (Sass, Less etc.)
• Adding Images and Fonts
• Using the app/assets Folder
  • Changing the HTML
  • Adding Assets Outside of the Module System
  • When to Use the app/assets Folder
• Using Global Variables
• Adding Bootstrap
• Adding Flow
• Adding Custom Environment Variables
  • Referencing Environment Variables in the HTML
  • Adding Temporary Environment Variables In Your Shell
  • Adding Development Environment Variables In .env
• Can I Use Decorators?
• Integrating with an API Backend
  • Node
  • Ruby on Rails
• Proxying API Requests in Development
• Using HTTPS in Development
• Generating Dynamic <meta> Tags on the Server
• Injecting Data from the Server into the Page
• Running Tests
  • Filename Conventions
  • Command Line Interface
  • Version Control Integration
  • Writing Tests
  • Testing Components
  • Using Third Party Assertion Libraries
  • Initializing Test Environment
  • Focusing and Excluding Tests
  • Coverage Reporting
  • Continuous Integration
  • Disabling jsdom
  • Snapshot Testing
  • Editor Integration
• Developing Components in Isolation
• Making a Progressive Web App
• Deployment
  • Serving Apps with Client-Side Routing
  • Building for Relative Paths
  • Azure
  • Firebase
  • GitHub Pages
  • Heroku
  • Modulus
  • Netlify
  • Now
  • S3 and CloudFront
  • Surge
• Advanced Configuration
• Troubleshooting
  • npm start doesn’t detect changes
  • npm test hangs on macOS Sierra
  • npm run build silently fails
  • npm run build fails on Heroku
• Something Missing?

Updating to New Releases

NodeKit Command Line is divided into two packages:

• nodekit is a global command-line utility that you use to create new projects.
• nodekit-scripts is a development dependency in the generated projects (including this one).

You almost never need to update nodekit itself: it delegates all the setup to nodekit-scripts and platforms (macos, ios, android, windows, etc.) are updated just like any npm/yarn dependency.

When you run nodekit, it always creates the project with the latest version of nodekit-scripts so you’ll get all the new features and improvements in newly created apps automatically.

To update an existing project to a new version of nodekit-scripts, open the changelog, find the version you’re currently on (check package.json in this folder if you’re not sure), and apply the migration instructions for the newer versions.

In most cases bumping the nodekit-scripts version in package.json and running npm install in this folder should be enough, but it’s good to consult the changelog for potential breaking changes.

We commit to keeping the breaking changes minimal so you can upgrade nodekit-scripts painlessly.

Sending Feedback

We are always open to your feedback.

Folder Structure

After creation, your project should look like this:

my-app/
  README.md
  node_modules/
  package.json
  app/
    assets/
      index.html
      favicon.ico
    App.css
    App.js
    App.test.js
    index.css
    index.js
    logo.svg
  platforms/

For the project to build, these files must exist with exact filenames:

• apps/assets/index.html is the page template;
• app/index.js is the JavaScript entry point.

You can delete or rename the other files. You can override these directories in the `package.json' file.

You may create subdirectories inside app. For faster rebuilds, only files inside app are processed by FuseBox, the JavaScript packager used in this template
You need to put any JS and CSS files inside app, or FuseBox won’t see them.

Only files inside app/assets can be used from app/assets/index.html.
Read instructions below for using assets from JavaScript and HTML.

You can, however, create more top-level directories.
They will not be included in the production build so you can use them for things like documentation.

Available Scripts

In the project directory, you can run:

npm run platform -- add <platform>

Addes the platform (replace <platform> with macos, ios, android or windows)
This will download some template files that you can find in the platforms folder.

npm run build

Runs a full build including the packaging of the JavaScript files, updates to any configuration files, and compiles the native code for the platforms added using the npm run platform -- add <platform> commands.

npm run build -- <platform>

Runs a full build for the specified platform only

npm start

Runs the native app in the development mode.
Launches the desktop app or deploys to an attached development device, or local simulator.

Installing a Dependency

The generated project includes React and ReactDOM as dependencies. You may install other dependencies (for example, React Router) with npm:

npm install --save <library-name>

Importing a Component

This project setup supports ES6 modules thanks to Babel.
While you can still use require() and module.exports, we encourage you to use import and export instead.

For example:

Button.js

import React, { Component } from 'react';

class Button extends Component {
  render() {
    // ...
  }
}

export default Button; // Don’t forget to use export default!

DangerButton.js

import React, { Component } from 'react';
import Button from './Button'; // Import a component from another file

class DangerButton extends Component {
  render() {
    return <Button color="red" />;
  }
}

export default DangerButton;

Be aware of the difference between default and named exports. It is a common source of mistakes.

We suggest that you stick to using default imports and exports when a module only exports a single thing (for example, a component). That’s what you get when you use export default Button and import Button from './Button'.

Named exports are useful for utility modules that export several functions. A module may have at most one default export and as many named exports as you like.

Learn more about ES6 modules:

• When to use the curly braces?
• Exploring ES6: Modules
• Understanding ES6: Modules

Adding a Stylesheet

This project setup uses Fusebox for handling all assets.

Button.css

.Button {
  padding: 20px;
}

Button.js

import React, { Component } from 'react';
import './Button.css'; // Tell FuseBox that Button.js uses these styles

class Button extends Component {
  render() {
    // You can use them as regular CSS styles
    return <div className="Button" />;
  }
}

Adding Images and Fonts

With FuseBox, using static assets like images and fonts works similarly to CSS.

You can import an image right in a JavaScript module. This tells FuseBox to include that image in the bundle. Unlike CSS imports, importing an image or a font gives you a string value. This value is the final image path you can reference in your code.

Here is an example:

import React from 'react';
import logo from './logo.png'; // Tell FuseBox this JS file uses this image

console.log(logo); // /logo.84287d09.png

function Header() {
  // Import result is the URL of your image
  return <img src={logo} alt="Logo" />;
}

export default Header;

This ensures that when the project is built, FuseBox will correctly move the images into the build folder, and provide us with correct paths.

This works in CSS too:

.Logo {
  background-image: url(./logo.png);
}

FuseBox finds all relative module references in CSS (they start with ./) and replaces them with the final paths from the compiled bundle. If you make a typo or accidentally delete an important file, you will see a compilation error, just like when you import a non-existent JavaScript module. The final filenames in the compiled bundle are generated by FuseBox from content hashes. If the file content changes in the future, FuseBox will give it a different name in production so you don’t need to worry about long-term caching of assets.

Please be advised that this is also a custom feature of FuseBox.

It is not required for React but many people enjoy it (and React Native uses a similar mechanism for images).
An alternative way of handling static assets is described in the next section.

Using the app/assets Folder

Changing the HTML

The app/assets folder contains the HTML file so you can tweak it, for example, to set the page title. The <script> tag with the compiled code will be added to it automatically during the build process.

Adding Assets Outside of the Module System

You can also add other assets to the app/assets folder.

Note that we normally encourage you to import assets in JavaScript files instead. For example, see the sections on adding a stylesheet and adding images and fonts. This mechanism provides a number of benefits:

• Scripts and stylesheets get minified and bundled together to avoid extra network requests.
• Missing files cause compilation errors instead of 404 errors for your users.
• Result filenames include content hashes so you don’t need to worry about browsers caching their old versions.

However there is an escape hatch that you can use to add an asset outside of the module system.

If you put a file into the app/assets folder, it will not be processed by FuseBox. Instead it will be copied into the build folder untouched. To reference assets in the app/assets folder, you need to use a special variable called PUBLIC_URL.

Inside index.html, you can use it like this:

<link rel="shortcut icon" href="%PUBLIC_URL%/favicon.ico">

Only files inside the app/assets folder will be accessible by %PUBLIC_URL% prefix. If you need to use a file from src or node_modules, you’ll have to copy it there to explicitly specify your intention to make this file a part of the build.

When you run npm run build, Create React App will substitute %PUBLIC_URL% with a correct absolute path so your project works even if you use client-side routing or host it at a non-root URL.

In JavaScript code, you can use process.env.PUBLIC_URL for similar purposes:

render() {
  // Note: this is an escape hatch and should be used sparingly!
  // Normally we recommend using `import` for getting asset URLs
  // as described in “Adding Images and Fonts” above this section.
  return <img src={process.env.PUBLIC_URL + '/img/logo.png'} />;
}

Keep in mind the downsides of this approach:

• None of the files in app/assets folder get post-processed or minified.
• Missing files will not be called at compilation time, and will cause 404 errors for your users.
• Result filenames won’t include content hashes so you’ll need to add query arguments or rename them every time they change.

When to Use the app/assets Folder

Normally we recommend importing stylesheets, images, and fonts from JavaScript. The app/assets folder is useful as a workaround for a number of less common cases:

• You need a file with a specific name in the build output, such as manifest.webmanifest.
• You have thousands of images and need to dynamically reference their paths.
• You want to include a small script like pace.js outside of the bundled code.
• Some library may be incompatible with FuseBox and you have no other option but to include it as a <script> tag.

Note that if you add a <script> that declares global variables, you also need to read the next section on using them.

Something Missing?

If you have ideas for more “How To” recipes that should be on this page, let us know or contribute some!