rtsao / create-universal-package Goto Github PK

View Code? Open in Web Editor NEW

37.0 3.0 14.0 1.32 MB

📦 A toolchain for developing universal (Node.js and browser) JavaScript packages

License: MIT License

JavaScript 98.50% TypeScript 1.50%

create-universal-package's Introduction

create-universal-package

A toolchain for developing universal (Node.js and browser) JavaScript packages.

Installation

npm i create-universal-package --save-dev

Usage

  Usage: cup [options] [command]

  Commands:

    build, b     Build your package
    build-tests  Build your tests
    clean, c     Clean build artifacts
    help         Display help

  Options:

    -h, --help     Output usage information
    -v, --version  Output the version number

Tests

Any .js files at the root of any __tests__ directory will be added to the test bundle. For browser-only test files, you can use a .browser.js extension. This also works for node-only tests and .node.js.

Globals

`NODE` and `BROWSER`

Aliases for either true or false depending on the build target. Use this in conjunction with conditionals to check for environment, and dead code will automatically be eliminated appropriately.

For linting purposes, __BROWSER__ and/or __NODE__ conditional checks establish appropriate environment globals. For example:

process.title; // fails `cup/no-undef`
window.location; // fails `cup/no-undef`

// passes lint
if (__BROWSER__) {
  document.body.appendChild(document.createTextNode('hello world'));
}

// passes lint
if (__NODE__) {
  process.stdout.write('hello world');
}

// passes lint
const topLevel = __BROWSER__ ? window : global;

By default, only universal globals (e.g. setTimeout and console) are set everywhere.

`DEV`

Alias for process.env.NODE_ENV !== 'production'. By convention, it is assumed that module consumers are statically inlining the value of process.env.NODE_ENV in browser bundles.

Dependencies

create-universal-package prunes unused imports in scenarios like the following:

import doNodeThing from 'some-package';

export function foo() {
  console.log('foo');
  if (__NODE__) {
    doNodeThing();
  }
}

Node.js result

import doNodeThing from 'some-package';

export function foo() {
  console.log('foo');
  doNodeThing();
}

Browser result

export function foo() {
  console.log('foo');
}

Notice how the some-package import gets eliminated from the browser result. This is what we want, but keep in mind any dependencies that perform side effects when imported could be eliminated.

create-universal-package's People

Contributors

Stargazers

Watchers

Forkers

nadiia lhorie kevingrandon ganemone chrisdothtml nickeliah1 derekjuber micburks tajo zxbodya octohedron derekju shykisto

create-universal-package's Issues

Configuration file

A .cuprc.js or equivalent is probably necessary at this point.

Ideally the configuration should offer options for:

Target browser/node versions in browserlist format
Additional Babel presets/options

When exposing flow definitions with `forceFlow` maybe source files needs to be copied with `.flow` prefix

So the actual raw javascript files are not made public/accessible in the distributable unintentionally.

cc @lhorie

RFC: create-universal-package v4

Background

The original reason for pre-bundling libraries using Rollup has since been obviated by improvements in webpack v4. Additionally, since the introduction of the sideEffects: false package.json field, Rollup has become actually counterproductive in some instances with regard to tree shaking, sometimes breaking the limited scope analysis performed by webpack.

Proposed changes

Simplified output formats

Unlike in the past, the de facto standard of bundling/transpiling has now changed to always transpile valid ES2017+ inside node_modules when bundling browser code. Therefore, CUP can merely output a single ES2017+ output for browser code.

For server code, bundling node_modules is not yet standardized, so both CommonJS and ESM will need to be outputted for now. In terms of transpilation, the output should correspond to whatever is natively supported in Node.js) .

Replace bundling with file structure-preserving transpilation

Replace bundling with mirrored transpiled file structure, instead of bundling. Preserving file structure in transpiled directories avoids pitfalls bundlers.

For example:

src/
├── index.js
├── foo.js
└── bar.js
dist-browser-esm/ (generated)
├── index.js
├── foo.js
└── bar.js
dist-server-esm/ (generated)
├── index.js
├── foo.js
└── bar.js
dist-server-cjs/ (generated)
├── index.js
├── foo.js
└── bar.js

Replace Rollup tree shaking with babel-based import pruning

While not strictly necessary for Webpack v4+, this ensures that even bundlers without import pruning enabled will not bundle unreachable imports.

I've already implemented this as a babel plugin in babel-plugin-transform-prune-unused-imports

Enforce `sideEffects: false` in package.json

Universal packages should never depend on import side effects. Explicitly marking this as false allows bundlers to tree shake and prune unused/unreachable imports more effectively.

Flow and named export problem

Currently we will generate a .js.flow file like:

// @flow
export * from '../src/index.js';

This module has some code like:

import {styled} from 'styletron-react';
export {styled};

When upgrading to a new package built with create-universal-package, errors like the following appear:

Error: src/root.js:5
  5: import {styled} from 'fusion-plugin-styletron-react';
             ^^^^^^ Named import from module `fusion-plugin-styletron-react`. This module has no named export called `styled`.

If I manually edit the generated .js.flow file and append the following things seem to work again:

export {styled} from '../src/index.js';

It seems that there is some export * from flow issue. I have not found a root issue yet.

Versions:

Compatibility with yarn create command

We should redistribute the responsibilities of the packages so that it'll work with the yarn create workflow.

support for UMD build

I wanted to take a stab at adding a UMD build option if you are ok with it.

Some considerations for UMD:

Need some option to specify what the module name should be for UMD
Need to decide whether or not to bundle dependencies directly into package or expect them to be exposed via different global variable

Let me know your thoughts. Thanks

Enforce package.json "files" field is set to "dist"

CUP should ensure that the correct build artifacts are published to npm.

Reconsider test build process

It might be preferable to use webpack instead of rollup for building test entries, particularly for the browser.

To keep things robust, the entry files could be aliased to the rolled up build artifacts. This would ensure the test code is actually testing the built, rolled-up code.

Consider replacing Rollup w/ sideEffects: false

Webpack 4 has good support for import pruning / tree shaking if the package declares itself to be side effect free and consists of re-exports.

Provided consumers are using Webpack 4, this obviates the need for relying on Rollup for tree shaking.

Perhaps there should be a --supportLegacyBundlers flag to opt into attempting to perform tree shaking at prepare time.

Watch-build mode

There should be a watch mode to automatically rebuild on changes.

Output flow type annotations

Folks should be able to author packages with flow types then have CUP output separate annotation files correctly.

Don't hardcode babel-preset-env exclusions for ES2015 bundles

Once babel/babel-preset-env#376 is landed, the appropriate lists can simply be imported directly from the package itself.

Fails to build saying "Unexpected token, expected "," " when it hits React context component

I found that when I run into this code:

<Foo.Consumer>
{({bar}) => bar

I get an error Unexpected token, expected "," (61:26) which is where the . that splits the Foo and Consumer is. I am guessing that this does not recognize more recent React syntax since removing that makes the error go away.

Better stdout on CI

Perhaps disable progress spinners?

Add rollup-plugin-json

Currently, if you try to import a json file (e.g. package.json), you'll get an error:

SyntaxError: [...]/package.json: Unexpected token, expected ";" (2:8)
  1 | {
  2 |   "name": "foo-bar",
    |         ^

See this issue (old but still applies). tl;dr rollup doesn't parse json imports out of the box and you need rollup-plugin-json for it