formidablelabs / builder-react-component

A React component archetype for builder.

Builder Archetype: React Component

A React component archetype for builder.

Installation

To use the production and development workflows, install both this package and the development module:

$ npm install --save builder-react-component
$ npm install --save-dev builder-react-component-dev

Generator

To bootstrap a new project from scratch with template files from this archetype, you can use builder-init:

$ npm install -g builder-init
$ builder-init builder-react-component

This will download this archetype, prompt you for several template data values and inflate the archetype templates to real files at a chosen directory.

Project Structure

See the development guide for workflows associated with this archetype.

The archetype assumes a file structure like the following:

demo/
  app.js
  index.html
src
  components/
    *.js
  index.js
test
  client/
    spec/
      components/
        *.js
      *.js
    main.js
    test.html
.builderrc
package.json

This matches the builder-init templates found in the source of this archetype.

File / Component Name

The name field in package.json (the published npm package name) is assumed to be:

1. The desired file name of the distribution files and dash-cased.
2. The desired default exported class name when converted to PascalCase.

So, if a package.json has:

{
  "name": "my-cool-component"
}

The distribution files to output are:

dist/my-cool-component.js
dist/my-cool-component.js.map
dist/my-cool-component.min.js
dist/my-cool-component.min.js.map

and the exported class name is MyCoolComponent.

Usage Notes

This archetype does not currently specify its own .babelrc. Your project should specify its own in the root directory if you want non-default Babel settings (like using stage 0, for instance). See the recommended settings.

Tasks

$ builder help builder-react-component

Usage:

  builder <action> <task(s)>

Actions:

  run, concurrent, envs, help

Flags: General

  --builderrc: Path to builder config file (default: `.builderrc`)

  --help: Display help and exit

  --version: Display version and exit

  --quiet: Silence logging

  --log-level: Level to log at (`info`, `warn`, `error`, `none`)

  --env: JSON string of environment variables to add to process

  --env-path: JSON file path of environment variables to add to process

Tasks:

  npm:postinstall
    [builder-react-component] builder run build

  npm:postpublish
    [builder-react-component] publishr postpublish -V

  npm:postversion
    [builder-react-component] publishr postversion -V

  npm:preversion
    [builder-react-component] builder run check

  npm:test
    [builder-react-component] builder run test-frontend

  npm:version
    [builder-react-component] builder run clean && builder run build && git add -A dist

  build
    [builder-react-component] builder run build-libs && builder run build-dist

  build-babel
    [builder-react-component] babel src --copy-files

  build-dist
    [builder-react-component] builder run clean-dist && builder run build-dist-min && builder run build-dist-dev

  build-dist-dev
    [builder-react-component] webpack --bail --config node_modules/builder-react-component/config/webpack/webpack.config.dev.js --colors

  build-dist-min
    [builder-react-component] webpack --bail --config node_modules/builder-react-component/config/webpack/webpack.config.js --colors

  build-es
    [builder-react-component] builder run --env '{"BABEL_ENV":"es"}' build-babel -- -d es

  build-lib
    [builder-react-component] builder run --env '{"BABEL_ENV":"commonjs"}' build-babel -- -d lib

  build-libs
    [builder-react-component] builder concurrent --queue=1 build-lib build-es

  check
    [builder-react-component] builder run lint && builder run test

  check-ci
    [builder-react-component] builder run lint && builder run test-ci

  check-cov
    [builder-react-component] builder run lint && builder run test-cov

  check-dev
    [builder-react-component] builder run lint && builder run test-dev

  clean
    [builder-react-component] builder run clean-libs && builder run clean-dist

  clean-dist
    [builder-react-component] rimraf dist

  clean-libs
    [builder-react-component] rimraf es lib

  dev
    [builder-react-component] builder concurrent server-dev server-test

  hot
    [builder-react-component] builder concurrent server-hot server-test

  lint
    [builder-react-component] builder concurrent lint-server lint-client lint-client-test

  lint-client
    [builder-react-component] eslint --color -c node_modules/builder-react-component/config/eslint/.eslintrc-client src demo/*.js

  lint-client-test
    [builder-react-component] eslint --color -c node_modules/builder-react-component/config/eslint/.eslintrc-client-test src test/client

  lint-server
    [builder-react-component] eslint --color -c node_modules/builder-react-component/config/eslint/.eslintrc-server *.js

  open-demo
    [builder-react-component] opener http://127.0.0.1:3000

  open-dev
    [builder-react-component] builder concurrent dev open-demo

  open-hot
    [builder-react-component] builder concurrent hot open-demo

  server-dev
    [builder-react-component] webpack-dev-server --port 3000 --config node_modules/builder-react-component/config/webpack/demo/webpack.config.dev.js --colors --content-base demo

  server-hot
    [builder-react-component] webpack-dev-server --port 3000 --config node_modules/builder-react-component/config/webpack/demo/webpack.config.hot.js --colors --hot --content-base demo

  server-test
    [builder-react-component] webpack-dev-server --port 3001 --config node_modules/builder-react-component/config/webpack/webpack.config.test.js --colors

  test
    [builder-react-component] builder run npm:test

  test-ci
    [builder-react-component] builder run test-frontend-ci

  test-cov
    [builder-react-component] builder run test-frontend-cov

  test-dev
    [builder-react-component] builder run test-frontend-dev

  test-frontend
    [builder-react-component] karma start node_modules/builder-react-component/config/karma/karma.conf.js

  test-frontend-ci
    [builder-react-component] karma start --browsers PhantomJS,Firefox node_modules/builder-react-component/config/karma/karma.conf.coverage.js

  test-frontend-cov
    [builder-react-component] karma start node_modules/builder-react-component/config/karma/karma.conf.coverage.js

  test-frontend-dev
    [builder-react-component] karma start node_modules/builder-react-component/config/karma/karma.conf.dev.js

  version-dry-run
    [builder-react-component] publishr dry-run -V

builder-react-component's Issues

Add `--bail` to build-dist-min and build-dist-dev webpack tasks

This is required to get exit 0 status to support FormidableLabs/victory#98

Feature: Add `builder run <task> -- CLI ARGS`

Just like npm does it: https://docs.npmjs.com/cli/run-script

$ npm run-script <command> [-- <args>...]

As of [email protected], you can use custom arguments when executing scripts. The special option -- is used by getopt to delimit the end of the options. npm will pass all the arguments after the -- directly to your script:

$ npm run test -- --grep="pattern"

Docs: Add `Development.md` from `formidable-react-component-boilerplate`

Have archetype be the source of truth.

BUG: on npm 2 `builder postinstall` fails if builder package includes another builder package

Not sure whether this is an issue with the archetype or builder itself...

on repos that are using builder,npm install will fail if they include another package that uses builder.

failing CI on this repo is an example
FormidableLabs/victory-axis#40

Postinstall on windows needs quotes.

For C:\Documents[SPACE] in expanded archetype.

And possible bug with the space too...

BUG: Update demo webpack hot config (`demo/webpack.config.hot.js`)

In https://github.com/FormidableLabs/builder-react-component/blob/master/config/webpack/demo/webpack.config.hot.js#L9 we need something like:

// Update loaders array.
mod.loaders[0].loaders = [require.resolve("react-hot-loader")]
  .concat(mod.loaders[0].loader ? [mod.loaders[0].loader] : [])
  .concat(mod.loaders[0].loaders || []);

// Remove single loader if any.
mod.loaders[0].loader = null;

/cc @coopy @boygirl

Build Strategy - Remove `lib/` and `dist/` from git source.

Task:

• Remove dist/ and lib/ from source
• Build dist/ and lib/ if installed off git with some sensible approach
• Ideally keep "building" deps out of dependencies
• And accept losing bower installs (which can't build)
• Update docs on "usage" scenarios: CJS, webpack, AMD, lib, vanillajs, npmcdn, etc.

Research:

• Radium did this in FormidableLabs/radium@90f353b but hit bug FormidableLabs/radium#548 We'll watch this for more.

Build on windows...

I have issues when trying to run the build scripts of the package.json.
When running builder run build (for example), it complains

undefined:1
'{BABEL_ENV:commonjs}'
^

SyntaxError: Unexpected token ' in JSON at position 0
    at JSON.parse (<anonymous>)
    at parse (C:\somepath\node_modules\builder\lib\utils\json.js:36:19)
    at module.exports.Environment.updateEnvFlag (C:\somepath\node_modules\builder\lib\environment.js:153:17)
    at new module.exports (C:\somepath\node_modules\builder\lib\environment.js:64:8)
    at module.exports (C:\somepath\node_modules\builder\bin\builder-core.js:32:13)
    at Object.<anonymous> (C:\somepath\node_modules\builder\bin\builder.js:43:1)
    at Module._compile (module.js:624:30)
    at Object.Module._extensions..js (module.js:635:10)
    at Module.load (module.js:545:32)
    at tryModuleLoad (module.js:508:12)

It's most certainly a problem with my windows dev box... In fact, it complains because the string given as argument through --env is not escaped properly.

I've manage to fix it by changing these lines:

"build-es": "builder run --env '{\"BABEL_ENV\":\"es\"}' build-babel -- -d es"
"build-lib": "builder run --env '{\"BABEL_ENV\":\"commonjs\"}' build-babel -- -d lib",

into:

"build-es": "builder run --env \"{\\\"BABEL_ENV\\\":\\\"es\\\"}\" build-babel -- -d es"
"build-lib": "builder run --env \"{\\\"BABEL_ENV\\\":\\\"commonjs\\\"}\" build-babel -- -d lib",

What is wrong ? is it my setup ? my node ?

BUG: .babelrc is not explicitly pointed to everywhere, sometimes doesn't get used

As @boygirl found in FormidableLabs/victory-component-boilerplate#11, using the @Radium syntax in the new Builder-based victory-component-boilerplate doesn't work, because Babel isn't always getting its config from our .babelrc and thus uses the default settings.

With decorator syntax, this uses the correct .babelrc and works: builder run build-lib

These do NOT work: builder run build-dist and builder run test-frontend

Addng .babelrc to ROOT makes it work, but we don't want to have to do that.

We need a way to pass along our .babelrc path to Webpack (for building dist and testing) and isparta (for coverage) – the latter probably being the most difficult as I don't think an option is exposed.

/cc @ryan-roemer @boygirl

Package: Remove `concurrently`

Replace with builder built in.

Feature: Add `css`, `png` files to a boilerplate and test with `builder-react-component`

Feature: Karma dev watchers.

• First, see if we don't need to implement this ticket but can instead document how to do easy watching using the new builder <action> <task(s)> -- ARBITRARY COMMAND LINE FLAGS functionality to just pass -- --watch or something meaningful to karma on the command line. Might still need at least a separate task to watch known directories, etc. (Talk to Ryan if this doesn't make sense).
• If so, just document how to watch in DEVELOPMENT.md
• If not, implement new tasks as follows:

Need a karma config something like:

module.exports = function (config) {
  config.set({
    frameworks: ["mocha", "phantomjs-shim"],
    reporters: ["spec"],
    browsers: ["PhantomJS"],
    basePath: process.cwd(), // repository root.
    files: [
      // Test bundle (must be created via `npm run dev|hot|server-test`)
      "http://127.0.0.1:3001/assets/bundle.js",

      // Watch files for re-running tests.
    ].concat([
      "demo/**",
      "src/**",
      "test/**"
    ].map(function (pattern) {
      return { pattern: pattern, included: false, served: false, watched: true };
    })),
    port: 9999,
    singleRun: true,
    client: {
      mocha: {
        ui: "bdd"
      }
    }
  });
};

and archetype task of:

"test-frontend-dev-watch": "karma start node_modules/@walmart/electrode-archetype-react-component/config/karma/karma.conf.dev.js --colors --browsers Chrome --no-single-run --auto-watch",

ARCHETYPE-dev: Copy README.md on publish.

Ignored by .gitignore, included with .npmignore

Extract `util/dev.js` / prod/dev dependencies Archetype publishing

From @chaseadamsio

If you decide to go either route, it might make sense to abstract util/dev.js into its own package so that anyone who wanted to create builder archetypes could just use it without having to know how to use the script or update it whenever you decide to update it...it might even make sense to make it a part of builder as a task, something like: builder publish archetype inside of a repository that would publish your archetype and the -dev version for you.

BUG: Need `require.resolve("css-loader") in webpack config?

Add initial "prompts" to builder-support?

I was working on a builder archetype from scratch this morning just for kicks and giggles and my init.js is going to look exactly like the following lines in the prompts:

https://github.com/FormidableLabs/builder-react-component/blob/master/init.js#L30-L60

This is probably getting super meta, but @ryan-roemer what do you think about having builder-support allow you to init and init.js with specific values?

Travis CI: Test scenarios

• builder init a fully new package into TEMP/ and run builder run check-ci
• Make a TEMP2 and npm install ../TEMP to flush out npm install bugs like FormidableLabs/builder#25

Remove any `test` and `start` script in archetype

Leave "npm special" script names (test, start) for project to implement.

`builder-init`: Init project and run CI.

script:
  # Check archetype.
  - npm --version
  - npm run builder:check

  # Check init templates
  - "npm install -g FormidableLabs/builder-init#chore-init-install" # TODO: Update to npm version
  - mkdir .builder-init-tmp
  - cd .builder-init-tmp
  - >-
    builder-init $PWD/.. --prompts='{
    "packageName":"whiz-bang",
    "packageGitHubOrg":"Acme",
    "licenseDate":"2016",
    "licenseOrg":"Acme",
    "destination":"whiz-bang"}'
  - cd whiz-bang
  - npm install

  # Run initialized project's own CI
  - npm --version
  - node_modules/.bin/builder run check-ci
  - npm prune --production
  - node_modules/.bin/builder run build

CI: Greenkeeper

• Hook up greenkeeper
• Relies on builder-init being part of CI to test / verify.
• Hook to / harmonize with semantic versioned releases.

Switch from global `sinon` to imported `sinon`

Sinon currently does not play well with Webpack due to non-standard UMD configuration. We currently globally include it.

TASK:

• Update webpack.config.*.js to use:

  // Add sinon hacks to work with webpack.
  // https://github.com/webpack/webpack/issues/304
  module: {
      noParse: [
          /node_modules\/sinon\//,
      ]
  },
  resolve: {
      alias: {
          sinon: require.resolve("sinon/pkg/sinon")
      }
  }

• Remove window.sinon, global.sinon references.

• Retrofit all test code to require("sinon") or import sinon from "sinon";

• Remove eslint exceptions for sinon global.

• Remove global sinon from Karma configs

  • builder-react-component/config/karma/karma.conf.dev.js

    Lines 17 to 19 in 8629358

    	// Sinon has issues with webpack. Do global include.
    	require.resolve("sinon/pkg/sinon"),

  • builder-react-component/config/karma/karma.conf.js

    Lines 27 to 28 in 8629358

    	// Sinon has issues with webpack. Do global include.
    	require.resolve("sinon/pkg/sinon"),

• Retrofit generator code:

  • https://github.com/FormidableLabs/formidable-react-component-boilerplate/blob/bd0e061ec3e27282d165def790437b326a6d543a/test/client/test.html#L13

References:

• webpack/webpack#304
• sinonjs/sinon#600 (comment)

webpack-dev-server parameter --host

How can I run webpack-dev-server bind in host 0.0.0.0, I need to develop on the remote machine.

builder run server-dev --host 0.0.0.0

It's not work.