Skip to content

Commit

Permalink
bun build docs in readme
Browse files Browse the repository at this point in the history
  • Loading branch information
jmuzina committed Oct 10, 2024
1 parent 1160f4b commit ac62f64
Show file tree
Hide file tree
Showing 2 changed files with 68 additions and 7 deletions.
73 changes: 67 additions & 6 deletions packages/ds/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,81 @@ 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

### TSConfig

#### 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`.
2 changes: 1 addition & 1 deletion packages/ds/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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}",
Expand Down

0 comments on commit ac62f64

Please sign in to comment.