Update Babel transpilation options

.gitignore

@@ -4,5 +4,6 @@ node_modules
 coverage/
 dist/
 lib/
+lib-esm/
 public/
 stats.html

babel.config.js

@@ -12,7 +12,7 @@ const sharedPlugins = [
   '@babel/plugin-proposal-object-rest-spread'
 ]
 
-const devPlugins = [['@babel/plugin-transform-runtime', {version: '7.9.2', helpers: true}]]
+const runtimePlugins = [['@babel/plugin-transform-runtime', {version: '7.9.2', helpers: true}]]
 
 function makePresets(moduleValue) {
   return [
@@ -24,12 +24,12 @@ function makePresets(moduleValue) {
 module.exports = {
   env: {
     development: {
-      presets: makePresets('commonjs'),
-      plugins: [...sharedPlugins, ...devPlugins, replacementPlugin('development')]
+      presets: makePresets(process.env.BABEL_MODULE || false),
+      plugins: [...sharedPlugins, ...runtimePlugins, replacementPlugin('development')]
     },
     production: {
       presets: makePresets(false),
-      plugins: [...sharedPlugins, replacementPlugin('production')]
+      plugins: [...sharedPlugins, ...runtimePlugins, replacementPlugin('production')]
     },
     test: {
       presets: makePresets('commonjs'),

docs/content/getting-started.md

@@ -17,17 +17,28 @@ yarn add @primer/components react react-dom styled-components
 You can now import Primer Components from the main package module:
 
 ```javascript
+// using import syntax
 import {Box, Flex} from '@primer/components'
+
+// using require syntax
+const {Box, Flex} = require('@primer/components')
 ```
 
 Alternatively, you can import individual components from the `lib` subfolder:
 
 ```javascript
+// using import syntax
 import Box from '@primer/components/lib/Box'
 import Flex from '@primer/components/lib/Flex'
+
+// using require syntax
+const Box = require('@primer/components/lib/Box')
+const Flex = require('@primer/components/lib/Flex')
 ```
 
-Importing components individually can reduce bundle sizes if you don't have tree-shaking set up in your app.
+Note that the files in the `lib` folder are CommonJS-style modules; if you're using ECMAScript modules (ESM) and a compatible module bundler, importing files individually from `lib` provides no benefit, as unused modules from the ESM build will be removed via tree-shaking. Primer Components has an ESM build specified in its `package.json`, so when using ESM you should always import components from the main entry point (as in the first example, above).
+
+If you're *not* using ESM, importing components individually from the `lib` folder may drastically decrease your final bundle size, since your module bundler will not have to include the entirety of Primer Components in your bundle.
 
 ### Peer dependencies
 

package.json

@@ -3,14 +3,15 @@
   "version": "19.0.0",
   "description": "Primer react components",
   "main": "lib/index.js",
-  "module": "lib/index.js",
+  "module": "lib-esm/index.js",
   "typings": "index.d.ts",
   "scripts": {
     "start": "cd docs && yarn run develop",
     "predist": "rm -rf dist",
-    "dist": "yarn dist:rollup && yarn dist:transpile",
+    "dist": "yarn dist:rollup && yarn dist:transpile:cjs && yarn dist:transpile:esm",
     "dist:rollup": "cross-env NODE_ENV=production rollup -c",
-    "dist:transpile": "rm -rf lib && babel src --out-dir lib",
+    "dist:transpile:cjs": "rm -rf lib && cross-env BABEL_MODULE=commonjs babel src --out-dir lib",
+    "dist:transpile:esm": "rm -rf lib-esm && babel src --out-dir lib-esm",
     "prepublishOnly": "yarn run dist",
     "lint": "eslint src docs/components",
     "test": "jest -- src",
@@ -31,8 +32,10 @@
     "codemods",
     "dist",
     "lib",
+    "lib-esm",
     "index.d.ts",
-    "!lib/__tests__"
+    "!lib/__tests__",
+    "!lib-esm/__tests__"
   ],
   "author": "GitHub, Inc.",
   "license": "MIT",

rollup.config.js

@@ -11,9 +11,9 @@ const namedExports = {
   'react-is': ['isValidElementType']
 }
 
-const formats = ['esm', 'umd'] // 'cjs' ?
+const formats = ['esm', 'umd']
 const plugins = [
-  babel({exclude: 'node_modules/**'}),
+  babel({exclude: 'node_modules/**', runtimeHelpers: true}),
   resolve(),
   commonjs({namedExports}),
   terser(),
@@ -23,8 +23,8 @@ const plugins = [
 export default [
   {
     input: 'src/index.js',
-    plugins,
     external: ['styled-components', 'react', 'react-dom'],
+    plugins,
     output: formats.map(format => ({
       file: `dist/browser.${format}.js`,
       format,