Publish Design System React to NPM

[vernak2539]

Can we get this lib published to NPM? It's kind of a headache to link to it via git url

[interactivellama]

The first purpose of open sourcing was to eliminate the access issue for folks. NPM publishing is in the plans. I don't have an ETA right now. I am evaluating the file structure of the module. Comments are welcome.

NPM module file structure

esnext/jsnext:main/module/*.mjs (“Michael Jackson Script”)...

Background

• https://nodesource.com/blog/es-modules-and-node-js-hard-choices/#currentstateofdiscussion (from 2016)
• Can we make the main dsr release (@salesforce/design-system-react) have both the dist files and the src files, with the src files referenced by jsnext:main?
• Could we potentially release "cleaner" versions that are postfixed? (@salesforce/design-system-react-cjs, @salesforce/design-system-react-ejs, @salesforce/design-system-react-amd, etc)
• Could we do subfolders? - @salesforce/design-system-react main points to @salesforce/design-system-react/cjs but you can also access @salesforce/design-system-react/ejs
• CommonJS transpile in root folder (default for node modules, linked to by package.main), require is synchronous
• ES6 modules transpiled in es folder (No JSX, no ES6 classes), linked to by package.jsnext:main and package.module), import is asynchronous and allows tree shaking by module builder

In a perfect “breaking changes” world

• dist/design-system-react.js (bundle)
• es/ (transpiled, except for import/export to allow tree shaking, no babel presets needed)
• src/ complete production source code
• lib/ commonjs transpiled (no babel presets needed)

A possibly non-breaking change proposal - use this

• [root]/design-system-react.js (UMD bundle, backwards compatible)
• [root] (ES6 tag file structure allows use of /components/ folder, transpiled to JS, except for import/export to allow tree shaking, no babel presets needed to read, backwards compatible with current ES6 tag-- maybe transpile to babel-preset-1?) used by import Button from 'design-system-react/components/button'
  * src/ complete production source code (has JSX, examples folder, etc.)
• lib/ commonjs transpiled (no babel presets needed, linked to from package.main, this would be backwards compatible as long as you didn't want real ES6 modules, this would also be compatible with create-react-app See Enable babel-preset-env for node_modules that target newer Node versions facebook/create-react-app#1125 which doesn't transpile node_modules ) so that import { Button } from 'design-system-react' would just work, because it uses CJS.

Benefits of non-breaking change proposal

• Doesn't break imports used in interactive examples for two years.
• Should be foreseeable future proof. main would be whatever would not have to be transpiled, and source would be transpiled to specific preset stage.
• Allows CommonJS via single entry point
  • Is CJS needed? Who builds React apps without a transpiler and a module builder?
• Ignore AMD version (still published from repo tag).
• UMD version is the bundled file.

if we are namespacing this with @salesforce, then we are beaking import from 'design-system-react' anyway, but that is an easy find and replace. ;-)

[interactivellama]

Consider new or no node engine spec for npm package. #1175

[futuremint]

I think the answer to your question, "Is CJS needed? Who builds React apps without a transpiler and a module builder?" is that we should not put any CJS-like things in the npm module. If you're using React in a CJS environment, you're likely already using some kind of transpiler to spit out the CJS modules that could also handle ES6 modules.

[futuremint]

I'm going to take this. The "normal" npm package (meaning when you would do npm install @salesforce/design-system-react will just be a pretty standard ES module setup. CJS and AMD things can be done other ways (either as another npm package, or just left up to engineering teams' build pipelines).

[interactivellama]

Sounds good. Feel free to pass it back at anytime. Most of the scripting should be present, especially if we aren't doing anything crazy like ES6+CJS. Mostly just needs some transpiling minus import/export, the bundled made and go. We can keep doing the CJS/AMD tags for a while or put a End of Life date on them a few major releases out.

[futuremint]

Yep, seeing that in the scripts. Probably just going to make a scripts/publish-to-npm.js that can be run after a npm run dist. EDIT: not going to use the tmp-es folder as it is merely a copy of the src files.

[vernak2539]

does that mean you're going to be publishing the components folder as it appears in the repo? or are you going to be compiling things down to ES5? Would be nice to have the source components in there, unbuilt

[futuremint]

Yes, there will be a index.js file which exports all of the components, and then also a components folder within the package that will have the individual components "lightly" transpiled (using a configuration of babel-env to normalize the exported code).

[futuremint]

@vernak2539 take a look at #1195, run npm run dist and look in the .tmp-npm folder it generates and see if the format of what is in ./components works for you.

[interactivellama]

After working some with Babel, I intend to make ./components/ the raw source code and not transpile the ./components folder.

I think the better path is to create a custom Babel preset that moves along with the library and pulls in any plugins needed. This means the source mapping is always correct, too. Class property initializers are still stage 2, for instance, so the source line numbers would be off for all class properties, and I'd like the application source maps to point to the actual source code so engineering teams can aid in debugging issues.

I intend to publish something along the lines of @salesforce/babel-preset-design-system-react that will published on NPM and allow whatever is used in the source code to be converted to their targeted browsers.

module.exports = function buildPreset (context, options) {
	return {
		presets: [
			require('@babel/preset-env').default(null, {
				modules: false,
				targets: {
					browsers: [
						'last 2 versions',
						'ie 11'
					],
					node: '6.10'
				}
			}),
			require('@babel/preset-react')
		],
		plugins: [
			require('@babel/plugin-proposal-object-rest-spread'),
			require('@babel/plugin-proposal-class-properties'),
			require('@babel/plugin-syntax-export-default-from'),
			require('@babel/plugin-syntax-export-extensions'),
			require('@babel/plugin-proposal-export-default')
		]
	};
};

Transpiled CommonJS will still be present in a lib folder for create-react-app, etc.

[gaearon]

FYI, we're starting the work to compile deps with babel-preset-env in Create React App: facebook/create-react-app#3776

Let us know if you have feedback about how this should work. Note we intentionally won’t be compiling JSX/Flow/etc, and will only stick to supporting features that work in Node.