diff --git a/packages/ds/README.md b/packages/ds/README.md index 4d9e63d8..491996e7 100644 --- a/packages/ds/README.md +++ b/packages/ds/README.md @@ -4,8 +4,10 @@ This template provides a minimal setup to get React working in Vite with HMR. Currently, two official plugins are available: -- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh -- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh +- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) + uses [Babel](https://babeljs.io/) for Fast Refresh +- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) + uses [SWC](https://swc.rs/) for Fast Refresh ## Caveats @@ -13,11 +15,70 @@ Currently, two official plugins are available: #### Skip library check -We use [skipLibCheck](https://www.typescriptlang.org/tsconfig/#skipLibCheck) to skip type checking of declaration files. -This is needed for compatibility with vite dependencies. If this option is not enabled, the following error occurs: - +We use [skipLibCheck](https://www.typescriptlang.org/tsconfig/#skipLibCheck) to +skip type checking of declaration files. This is needed for compatibility with +vite dependencies. If this option is not enabled, the following error occurs: ``` -../../node_modules/@storybook/react/dist/index.d.ts(3,188): error TS1479: The current file is a CommonJS module whose imports will produce 'require' calls; however, the referenced file is an ECMAScript module and cannot be imported with 'require'. Consider writing a dynamic 'import("storybook/internal/types")' call instead. +The current file is a CommonJS module whose imports will produce 'require' calls; however, the referenced file is an ECMAScript module and cannot be imported with 'require'. Consider writing a dynamic 'import("storybook/internal/types")' call instead. ``` + +### Bun + +[Bun](https://bun.sh/) is being experimentally used as a package manager. + +### Build tool + +Bun includes a [native JS bundler](https://bun.sh/docs/bundler) that can +transpile Typescript. + +#### Downsides + +We are not currently considering using `bun build` for production builds for +the following reasons: + +##### Globstar + +Bun's [implementation of globstar](https://bun.sh/docs/api/glob) is non-standard. +It is difficult to build arbitrarily deep filepaths, as Bun expects a globstar +for each level of supported nesting. Most glob implementations treat a globstar +as representing an arbitrary number of non-hidden directories. However, with +Bun, matching `.ts` files in `src/ui/Button` requires the glob pattern +`**/**/*.ts`, which does not match files in other levels of nesting. + +##### Dist Depth + +Generating `dist/` output that has the correct folder structure (i.e., +`dist/ui/Button/`) is non-trivial. `bun build` generates output with folder +structure starting from matching the shallowest source file. However, this is +not always desired. For example, if `ui/` is inside `src/`, one must `cd` into +`src` before running `bun build` to generate the appropriate folder structure. +You must then set build output to `../dist` to place build results in the +project root. This makes the build script unnecessarily complex. + +##### Type emitting + +`bun build` does not generate types, so it must be accompanied by the usage of +some other tool that generates type declarations. + +#### Upsides + +##### Speed + +Bun builds slightly faster than the Typescript compiler. + +| Tool | Command | Real Time | User Time | Sys Time | +| ---- | --------------------------------------------------------------------| --------- | --------- | -------- | +| Bun | `bun run build:package:bun` | 0m0.648s | 0m1.498s | 0m0.117s | +| Typescript | `bun run build:package:tsc && bun run build:package:copycss` | 0m0.707s | 0m1.615s | 0m0.094s | + +Note that the bun build must also call `tsc` to generate type declarations, and +the tsc build must call the external `copyfiles` dependency to copy assets into +`dist/`. + +##### Non-TS bundling + +`bun build` copies non-TS assets (such as images, stylesheets, etc) into `dist`. +`tsc` must be followed up with a manual step that copies non-TS files (currently, +this is only CSS) into `dist`. diff --git a/packages/ds/package.json b/packages/ds/package.json index d0829ab7..323b5254 100644 --- a/packages/ds/package.json +++ b/packages/ds/package.json @@ -9,7 +9,7 @@ "build:storybook": "bun run build-storybook", "build-storybook": "storybook build", "build:package": "bun run build:package:tsc && bun run build:package:copycss", - "build:package:bun": "bun build --root src src/**/**/*.{ts,tsx} --outdir dist/esm --sourcemap=linked --external '*' && bun run emit", + "build:package:bun": "bun build --root src src/**/**/*.{ts,tsx} --outdir dist/esm --sourcemap=linked --external '*' && tsc -p tsconfig.build.json --emitDeclarationOnly", "build:package:copycss": "copyfiles -u 1 src/ui/**/*.css dist/esm", "build:package:tsc": "tsc -p tsconfig.build.json", "lint": "biome lint src/**/*.{ts,tsx}",