@rexlabs/plz-cli

:pray: plz

CLI toolkit for frontend web dev @ rexlabs, enabling you to:

create :clap:

Generate new apps and npm packages!

develop :raised_hands:

Preview UI with Webpack Dev Server and Storybook!

test :ok_hand:

Run tests with Jest and Storyshot!

bundle :wave:

Build distributions with Babel and Webpack!

Rationale

Oh geez, another front dev tool... wrong!
This is a kit of tools - it says so in the first sentence. It is 💯 gud.

Frontend development is filled to the brim with open source tools like webpack, babel, jest and storybook. As great as they are, they're difficult to configure, don't play nice together, and each new tool introduces learning curves. Boo.

Rather than we all struggling through the pains of configuration setup and maintenance, in each app and package we build @ rexlabs, we invest all that tooling focus into plz.

It (plz 🙏) can sit in front of these tools, with a bunch of sane default configurations and hacks, to then be consistently employed in our projects.

Devs are given the opportunity to forget about tooling woes, freeing their minds for better tasks. What a pleasant experience!

Usage

$ plz help

Commands:
  create <name> [root-dir]  Generates a project called `@rexlabs/<name>`.
  test [options]            Starts a test runner in current directory.
  stories                   Starts a storybook for UI components.
  serve                     Starts an dev server for the project.
  build                     Bundles a project for distribution.
  clean                     Removes previously built files.
  help                      Shows this help message.

Help:
  --help, -h  Show help                                                [boolean]
  --help-all  Show all help                                            [boolean]

Options:
  --version, -v  Show cli version number                               [boolean]

Run `plz help <command>` for more info & options.

Create a new Project

plz create my-new-component

This will generate a new project in a folder called my-new-component.

Project Types

To change the type of project, use --project-type.

• react-component
• react-app
• module

Defaults to react-component project type.

Start Development

http://localhost:3000

App

plz serve

This will start a Webpack Dev Server with hot module replacement enabled, rebuilding your project on file changes.

Components

plz stories
plz stories --output-dir=./storybook-build

This will start a Storybook server, loading the src/.stories.js module. It can also be run from the root of a monorepo to load stories from each component package.

Running Tests

plz test
plz test --watch

This will start Jest, the Painless Test Runner™. It will look for files under __tests__ anywhere in the project.

Components

__tests__/storyshots.js

import plz from '@rexlabs/plz-cli';
plz.initStoryshots();

Components that have stories can use [Storyshot][storyshot] to snapshot the renders.

Bundling Projects

plz build

This will use Babel or Webpack, depending on the project type, to bundle the source of the project into browser-ready assets.

Configuration

Config for the plz 🙏 cli is resolved from established configuration files like other cli tools.

• The plz property in package.json file
• The .plzrc file (optionally with .json, .yaml, .js extensions)
• The .plz.config.js file

Available Options

Config Field	Description
projectType	One of the follow types: react-app, react-component, react-module
buildDir	The location of your project's build output. For apps this is public/. For modules this is at the root because modules output several bundle directories of their own: lib (cjs) module/ (esm)
cssModules	When enabled, CSS Modules can be imported into JS Modules. eg. import buttonStyles from './button-styles.css'.
runtimeCompilation	When enabled, packages found in node_modules/ that have a package.json plz:main field will be compiled & watched with Babel.
proxy	A map of proxy configs.
storybook	All options for Storybook's runtime. See @storybook/addon-options for more details. Additionally, babel and webpack properties can will defined, following the rules of the other config middleware.
babel	Middleware for the Babel config of the project. See the Example Config for more details.
webpack	Middleware for the Webpack config of the project. See the Example Config for more details.

CLI Arguments

Additionally, all config options can be overridden with cli args.

# Force the "react-app" configuration
plz build --project-type "react-app" --build-dir "./public"

# Change storybook nested configs
plz stories --storybook-show-down-panel

# Enable CSS Modules for developer server
plz serve --css-modules

Example Config

.plzrc.js or plz.config.js

module.exports = {
  projectType: "react-app",
  buildDir: './app-build',
  cssModules: false,
  runtimeCompilation: true,
  proxy: {
      '/api/v1': { target: 'http://localhost:8080' }
  },
  storybook: {
    url: ,
    goFullScreen: false,
    showLeftPanel: true,
    showDownPanel: true,
    showSearchBox: false,
    downPanelInRight: true,
    sortStoriesByKind: false
  },
  babel: (babelConfig) => {
    // ...transform the config if required!
    return transformedBabelConfig;
  },
  webpack: (webpackConfig) => {
    // ...transform the config if required!
    return transformedWebpackConfig;
  }
}

Proxy Config

Cross Origin issues are a pain that we usually encounter in development environments.

• A local API server uses another domain or port
  Not an issue if you have CORS setup!
• A local server might be hosting an embedded frame

To this goal, you can route requests through the App's Webpack Dev Server instance, by matching a request's path to a domain.

The extent of configuration is better explained in the underlying http-proxy-middleware, but common configuration is covered below.

.plzrc.js

module.exports = {
  proxy: {
    {
      '/api/v1': { target: 'http://localhost:8080' } /*
       \_____/    \_______________________________/
          |                     |
       context               options                  */
    }
  }
}

This will proxy the following shaped requests from the Webpack Dev Server to the "target" and back:

• http://localhost:3000/api/v1/accounts ➞ http://localhost:8080/api/v1/accounts.

Contributing

Structure

index.js
Start of CLI

src/commands/
Bulk of CLI logic is here, taking different paths for differing project types.

src/configs/
All the configuration for underlying tools.

Testing

# Watch for changes, rerunning tests
$ yarn test:watch

# Run watch once
$ yarn test

Re-generating cool ASCII logo

# The logo should be pasted to src/utils/index.js
yarn ascii | clipcopy

Inject up-to-date usage in readme.md

# The usage info is injected into the readme
yarn update-readme