docs(bundler): update documentation for package-bundler (#5393)

* docs(bundler): add README for each preset * docs(bundler): link to presets from main README * docs(bundler): add docs for multiple entrypoints * docs(bundler): update docs about compatible TS module resolution
cultureamp · Dec 16, 2024 · d1c7587 · d1c7587
1 parent 5ac8212
commit d1c7587
Show file tree

Hide file tree

Showing 4 changed files with 305 additions and 140 deletions.
diff --git a/.changeset/pink-cars-walk.md b/.changeset/pink-cars-walk.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/package-bundler/README.md b/packages/package-bundler/README.md
@@ -8,165 +8,52 @@ ESM code is tree-shakeable.
 pnpm add -D @kaizen/package-bundler
 ```
 
-## build-shared-ui
+## Presets
 
-For shared UI packages. CSS modules and/or Tailwind will be included in the dist in a single stylesheet (`{PACKAGE_NAME}/dist/styles.css`) to be imported by the consumer.
+- [Default preset](src/presets/default/README.md)
+- [Shared UI preset](src/presets/shared-ui/README.md)
 
-_Note: If your package extends another shared UI package, you will need to list the other package as a peerDependency and have the end consumer import both stylesheets._
+## Package entrypoints
 
-### `package.json`
+Depending on the compatibility you wish to provide for your consumer, you may need to define your `package.json` differently.
+Read more about [the different types of package.json entrypoints here](https://nodejs.org/api/packages.html#nodejs-packagejson-field-definitions).
 
-Add the following to your `package.json`:
+### Node 12+
 
-```json
-"main": "dist/cjs/index.cjs", // CommonJS entrypoint
-"module": "dist/esm/index.mjs", // ES modules entrypoint
-"types": "dist/types/index.d.ts", // TypeScript types entrypoint
-"files": [
-  "dist" // Ensure dist dir is included in package
-],
-"sideEffects": [
-  "styles.css" // Ensure styles do not get tree-shaken
-],
-"scripts": {
-  "build": "pnpm package-bundler build-shared-ui",
-}
-```
-
-#### Dependencies
-
-```sh
-pnpm add -D postcss postcss-preset-env rollup tslib
-```
-
-`devDependencies`:
-
-- `postcss`
-- `postcss-preset-env`
-- `rollup`
-- `tslib` (peerDep of `rollup`)
-- If using Tailwind:
-  - `tailwindcss`
-
-### Required files
+If your consumers are all using Node 12+ (including using TypeScript [`moduleResolution`](https://www.typescriptlang.org/tsconfig/#moduleResolution) `node16`/`nodenext`/`bundler`), you should be able to use the [`exports`](https://nodejs.org/api/packages.html#exports) field if you have multiple entrypoints.
 
-- `postcss.config.js`
-- `rollup.config.mjs`
-- `tsconfig.json`
-- `tsconfig.dist.json`
-- If using Tailwind:
-  - `tailwind.config.js`
-  - `src/tailwind.css`
+### Node <=10
 
-### PostCSS
+If your consumers may be using version 10 or lower (or are using TypeScript [`moduleResolution`](https://www.typescriptlang.org/tsconfig/#moduleResolution) `classic`/`node`/`node10`), the `exports` field will not be resolved. Your only option will be to utilise `main` (resolves CJS), `module` (resolves ESM), and `types` (resolves TypeScript).
 
-In `postcss.config.js`:
+Should you want multiple entrypoints, you will need to create a directory relative from the root of the package and create a `package.json` within that contains the extra resolutions.
 
-```js
-module.exports = {
-  plugins: {
-    'postcss-import': {},
-    'cssnano': {},
-  },
-}
-```
-
-If using Tailwind:
-
-```js
-module.exports = {
-  plugins: {
-    'postcss-import': {},
-    'tailwindcss/nesting': 'postcss-nesting',
-    'tailwindcss': {},
-    'autoprefixer': {},
-    'cssnano': {},
-  },
-}
-```
-
-### Rollup
+Eg. If we want to create an entrypoint at `@kaizen/package-bundler/future`:
 
-In `rollup.config.mjs`:
+Folder structure:
 
-```ts
-import { pluginsSharedUi, rollupConfig } from '@kaizen/package-bundler'
-
-export default rollupConfig({
-  // Add extra entrypoints as required
-  input: { index: './src/index.ts' },
-  plugins: pluginsSharedUi,
-})
+```md
+- future/
+  - package.json
+- src/...
+- package.json
 ```
 
-### tsconfig
+Contents for `future/package.json` (adjust your paths based on your defined dist structure).
 
 ```json
-// tsconfig.json
 {
-  "extends": "@kaizen/package-bundler/tsconfig.base.json"
-}
-
-// tsconfig.dist.json
-{
-  "extends": "./tsconfig.json"
-}
-```
-
-### Tailwind
-
-```sh
-pnpm add -D tailwind @kaizen/tailwind
-```
-
-Required files:
-
-- `tailwind.config.js`
-- `src/tailwind.css`
-
-Follow the [set up guide](../../docs/Tailwind/getting-started.mdx).
-
-As we use PostCSS, ensure your `postcss.config.js` has the following plugins installed:
-
-```js
-module.exports = {
-  plugins: {
-    'postcss-import': {},
-    'tailwindcss/nesting': 'postcss-nesting',
-    'tailwindcss': {},
-    'autoprefixer': {},
-    'cssnano': {},
-  },
-}
-```
-
-If you are creating a UI library to share with others, ensure you set a unique prefix to avoid clashes with other libraries.
-
-```js
-// tailwind.config.js
-module.exports = {
-  prefix: '{uniquePrefix}-',
+  "main": "../dist/cjs/future.cjs",
+  "module": "../dist/esm/future.mjs",
+  "types": "../dist/types/__future__/index.d.ts"
 }
 ```
 
-### Alias
-
-If you are using aliases, ensure you have them listed in your `tsconfig.json` (the `tsconfig.dist` should extend this).
-
-Example:
+You will also need to ensure that this directory is included in your distributed package, so in the main `package.json`, ensure the directory is included in `files`.
 
 ```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "paths": {
-      "~components/*": ["./src/*"],
-    }
-  }
-}
-
-// tsconfig.dist.json
-{
-  "extends": "./tsconfig.json",
-}
+"files": [
+  "dist",
+  "future"
+]
 ```
diff --git a/packages/package-bundler/src/presets/default/README.md b/packages/package-bundler/src/presets/default/README.md
@@ -0,0 +1,100 @@
+# Default preset
+
+For packages that do not contain any styles.
+
+### `package.json`
+
+Add the following to your `package.json`:
+
+```json
+"main": "dist/cjs/index.cjs", // CommonJS entrypoint
+"module": "dist/esm/index.mjs", // ES modules entrypoint
+"types": "dist/types/index.d.ts", // TypeScript types entrypoint
+"files": [
+  "dist" // Ensure dist dir is included in package
+],
+"scripts": {
+  "build": "pnpm package-bundler build",
+}
+```
+
+#### Dependencies
+
+```sh
+pnpm add -D rollup tslib
+```
+
+`devDependencies`:
+
+- `rollup`
+- `tslib` (peerDep of `rollup`)
+
+### Required files
+
+- `rollup.config.mjs`
+- `tsconfig.json`
+- `tsconfig.dist.json`
+
+### Rollup
+
+In `rollup.config.mjs`:
+
+```ts
+import { pluginsDefault, rollupConfig } from '@kaizen/package-bundler'
+
+export default rollupConfig({
+  // Add extra entrypoints as required
+  input: { index: './src/index.ts' },
+  plugins: pluginsDefault,
+})
+```
+
+### tsconfig
+
+```json
+// tsconfig.json
+{
+  "extends": "@kaizen/package-bundler/tsconfig.base.json",
+  // https://www.typescriptlang.org/tsconfig/#include
+  // Include all files you want TypeScript to resolve during development such as tests or stories eg.
+  "include": ["src/**/*", "__tests__/**/*"],
+  // https://www.typescriptlang.org/tsconfig/#exclude
+  // Files or patterns you want to exclude from your included files during development eg.
+  "exclude": ["node_modules"]
+}
+
+// tsconfig.dist.json
+{
+  "extends": "./tsconfig.json",
+  // https://www.typescriptlang.org/tsconfig/#include
+  // This overrides the value in the extended `tsconfig.json`
+  // Include all files you want TypeScript to resolve in the distributed package eg.
+  "include": ["src/**/*"],
+  // https://www.typescriptlang.org/tsconfig/#exclude
+  // This overrides the value in the extended `tsconfig.json`
+  // Files or patterns you want to exclude (such as tests and stories) from your included files in the distributed package eg.
+  "exclude": ["node_modules", "**/*.spec.ts", "**/*.spec.tsx", "**/*.stories.tsx"]
+}
+```
+
+### Alias
+
+If you are using aliases, ensure you have them listed in your `tsconfig.json` (the `tsconfig.dist` should extend this).
+
+Example:
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "paths": {
+      "~components/*": ["./src/*"],
+    }
+  }
+}
+
+// tsconfig.dist.json
+{
+  "extends": "./tsconfig.json",
+}
+```