Neutrino React Components Preset

@neutrinojs/react-components is a Neutrino preset that supports creating generic React components. Plays nicely with other Neutrino middleware, so you can build, test, and publish multiple React components from a single repository.

NPM version NPM downloads Join the Neutrino community on Spectrum

Features

  • Extends partially from @neutrinojs/react
  • Zero upfront configuration necessary to start developing and building React components.
  • Modern Babel compilation adding JSX, object rest spread syntax, and class properties.
  • Support for React Hot Loader
  • Write JSX in .js or .jsx files
  • Support for importing web workers with .worker.* file extensions
  • Extends partially from @neutrinojs/web
    • Modern Babel compilation supporting ES modules, last 2 major browser versions, async functions, and dynamic imports
    • webpack loaders for importing HTML, CSS, images, icons, fonts, and web workers
    • webpack Dev Server during development
    • Automatic stylesheet extraction; importing stylesheets into modules creates bundled external stylesheets
    • Pre-configured to support CSS Modules via *.module.css file extensions
    • Hot Module Replacement support including CSS
    • Tree-shaking to create smaller bundles
    • Production-optimized bundles with Babel minification, easy chunking, and scope-hoisted modules for faster execution
    • Easily extensible to customize your project as needed

Important! This preset does not include babel-polyfill for size reasons. If you need polyfills in your library code, consider importing babel-polyfill, core-js, or other alternative.

Requirements

  • Node.js v6 LTS, v8, v9
  • Yarn v1.2.1+, or npm v5.4+
  • Neutrino v8
  • React, React DOM

Installation

@neutrinojs/react-components can be installed via the Yarn or npm clients. Inside your project, make sure neutrino and @neutrinojs/react-components are development dependencies. You will also need React and React DOM for actual component development.

Yarn

❯ yarn add --dev neutrino @neutrinojs/react-components
❯ yarn add react react-dom

npm

npm install --save-dev neutrino @neutrinojs/react-components
❯ npm install --save react react-dom

If you want to have automatically wired sourcemaps added to your project, add source-map-support:

Yarn

❯ yarn add source-map-support

npm

npm install --save source-map-support

Project Layout

@neutrinojs/react-components follows the standard project layout specified by Neutrino. This means that by default all project source code should live in a directory named src in the root of the project. This includes JavaScript files that would be available to your compiled project.

All components should be their own module within a directory named components inside the source directory.

Quickstart

The fastest way to get started is by using the create-project scaffolding tool. Don’t want to use the CLI helper? No worries, we have you covered with the manual installation.

create-project

Run the following command to start the process. Substitute <directory-name> with the directory name you wish to create for this project.

Yarn

❯ yarn create @neutrinojs/project <directory-name>

Note: The create command is a shorthand that helps you do two things at once. See the Yarn create docs for more details.

npm/npx

npx comes pre-installed with npm. If you’re running an older version of npm, then npm install -g npm to update to the latest version.

❯ npx @neutrinojs/create-project <directory-name>

The CLI helper will prompt for the project to scaffold, and will offer to set up a test runner as well as linting to your project. Refer to the Create new project section for details on all available options.

Manual Installation

After installing Neutrino and this preset, add a new directory named src in the root of the project, with a single JS file named index.js in it. This index file can be used to render any components you wish to the browser to preview and.

mkdir src && touch src/index.js

Your components will go in a components directory inside src:

mkdir src/components

Edit your src/index.js file with the following:

import React from 'react';
import { render } from 'react-dom';
import YourCustomComponent from './components/YourCustomComponent';

const root = document.getElementById('root');

render((
  <YourCustomComponent />
), root);

Now edit your project's package.json to add commands for starting the development server, or building the components.

{
  "scripts": {
    "start": "neutrino start --use @neutrinojs/react-components",
    "build": "neutrino build --use @neutrinojs/react-components"
  }
}

If you are using .neutrinorc.js, add this preset to your use array instead of --use flags:

module.exports = {
  use: ['@neutrinojs/react-components']
};

Start the app, then open a browser to http://localhost:5000 to preview your components:

Yarn

❯ yarn start

✔ Development server running on: http://localhost:5000
✔ Build completed

npm

npm start

✔ Development server running on: http://localhost:5000
✔ Build completed

Building

@neutrinojs/react-components builds components to the build directory by default when running neutrino build. Using the quick start example above as a reference:

❯ yarn build

✔ Building project completed
Hash: 453804a130a959d313a1
Version: webpack 3.6.1
Time: 350ms
                     Asset     Size  Chunks             Chunk Names
    YourCustomComponent.js  4.12 kB       0  [emitted]  YourCustomComponent
YourCustomComponent.js.map  4.11 kB       0  [emitted]  YourCustomComponent
✨  Done in 3.69s.

You can then publish these components to npm. When publishing your project to npm, consider excluding your src directory in package.json by using the files property to whitelist build, or via .npmignore to blacklist src. Components are generated as UMD named modules, with the name corresponding to the component file name. e.g. src/components/Custom/index.js maps to Custom, as well as src/components/Custom.js mapping to Custom.

These modules are ES-compatible modules, so they can be imported as expected. If you want to use them with CJS require, you'll need to use the .default property to access the default exports:

const YourCustomComponent = require('your-custom-component').default;

By default this preset creates an individual entry point for every top-level component found in src/components. These are set and accessible via the API at neutrino.options.mains.

Hot Module Replacement

While @neutrinojs/react-components supports Hot Module Replacement for your app, it does require some changes to the preview app in order to operate. The preview app should define split points for which to accept modules (Components) to reload using module.hot. See the React preset docs for guidance.

Customizing

To override the build configuration, start with the documentation on customization. @neutrinojs/react-components uses a few rules and plugins in addition to the ones in use by the React and Web presets. See the Web documentation customization for preset-specific configuration to override.

By default this preset creates an individual entry point for every top-level component found in src/components. These are set and accessible via the API at neutrino.options.mains.

Rules

This plugin does not define any additional rules or loaders in addition to those already used by @neutrinojs/web and @neutrinojs/react.

Plugins

The following is a list of plugins and their identifiers which can be overridden (in addition to the plugins used by the React/Web presets):

Note: Some plugins are only available in certain environments. To override them, they should be modified conditionally.

Name Description Environments
banner Injects source-map-support into the mains (entry points) of your application if detected in dependencies or devDependencies of your package.json. all but development

By following the customization guide and knowing the rule, loader, and plugin IDs above, you can override and augment the build by by providing a function to your .neutrinorc.js use array. You can also make these changes from the Neutrino API in custom middleware.

Example: Change the name of the components directory:

module.exports = {
  use: [
    ['@neutrinojs/react-components', {
      components: 'react-stuff' // now you can put your components in src/react-stuff/
    }]
  ]
}

results matching ""

    No results matching ""