mirror of
https://github.com/oven-sh/bun
synced 2026-02-02 15:08:46 +00:00
Update README.md
This commit is contained in:
Jarred Sumner
294
README.md
294
README.md
@@ -404,7 +404,7 @@ type Router = {
|
||||
|
||||
To use a framework, you pass `bun bun --use package-name`.
|
||||
|
||||
Your framework's package.json `name` should start with `bun-framework-`. This is so that people can type something like `bun bun --use next` and it will check `bun-framework-next` first. This is similar to how Babel plugins tend to start with `babel-plugin-`.
|
||||
Your framework's `package.json` `name` should start with `bun-framework-`. This is so that people can type something like `bun bun --use next` and it will check `bun-framework-next` first. This is similar to how Babel plugins tend to start with `babel-plugin-`.
|
||||
|
||||
For developing frameworks, you can also do `bun bun --use ./relative-path-to-framework`.
|
||||
|
||||
@@ -412,6 +412,152 @@ If you're interested in adding a framework integration, please reach out. There'
|
||||
|
||||
# Reference
|
||||
|
||||
### `bun create`
|
||||
|
||||
`bun create` is a fast way to create a new project from a template.
|
||||
|
||||
At the time of writing, `bun create react app` runs ~14x faster on my local computer than `yarn create react-app app`. `bun create` currently does no caching (though your npm client does)
|
||||
|
||||
#### Usage
|
||||
|
||||
By default, templates are downloaded from folders inside `examples/` in Bun's GitHub repo. Running `bun create react ./local-path` downloads the `react` folder from `examples/react`.
|
||||
|
||||
Create a new Next.js project:
|
||||
|
||||
```bash
|
||||
bun create next ./app`
|
||||
```
|
||||
|
||||
Create a new React project:
|
||||
|
||||
```bash
|
||||
bun create react ./app
|
||||
```
|
||||
|
||||
To see a list of available templates, run
|
||||
|
||||
```bash
|
||||
bun create
|
||||
```
|
||||
|
||||
##### Local templates
|
||||
|
||||
If you have your own boilerplate you prefer using, copy it into `$HOME/.bun-create/my-boilerplate-name`.
|
||||
|
||||
Before checking Bun's examples folder, `bun create` checks for a local folder matching the input in:
|
||||
|
||||
- `$BUN_CREATE_DIR/`
|
||||
- `$HOME/.bun-create/`
|
||||
- `$(pwd)/.bun-create/`
|
||||
|
||||
If a folder exists in any of those folders with the input, bun will use that instead of a remote template.
|
||||
|
||||
This lets you run:
|
||||
|
||||
```bash
|
||||
bun create my-boilerplate ./app
|
||||
```
|
||||
|
||||
Now your new template should appear when you run:
|
||||
|
||||
```bash
|
||||
bun create
|
||||
```
|
||||
|
||||
Warning: unlike with remote templates, **bun will delete the entire destination folder if it already exists.**
|
||||
|
||||
##### Flags
|
||||
|
||||
| Flag | Description |
|
||||
| ---------------------- | -------------------------------------- |
|
||||
| --npm | Use `npm` for tasks & install |
|
||||
| --yarn | Use `yarn` for tasks & install |
|
||||
| --pnpm | Use `pnpm` for tasks & install |
|
||||
| --force | Overwrite existing files |
|
||||
| --no-install | Skip installing `node_modules` & tasks |
|
||||
| --no-git | Don't initialize a git repository |
|
||||
| ---------------------- | ----------------------------------- |
|
||||
|
||||
By default, `bun create` will cancel if there are existing files it would overwrite and its a remote template. You can pass `--force` to disable this behavior.
|
||||
|
||||
##### Publishing a new template
|
||||
|
||||
Clone this repository and a new folder in `examples/` with your new template. The `package.json` must have a `name` that starts with `@bun-examples/`. Do not worry about publishing it, that will happen automaticallly after the PR is merged.
|
||||
|
||||
Make sure to include a `.gitignore` that includes `node_modules` so that `node_modules` aren't checked in to git when people download the template.
|
||||
|
||||
##### Testing your new template
|
||||
|
||||
To test your new template, add it as a local template or pass the absolute path.
|
||||
|
||||
```bash
|
||||
bun create /path/to/my/new/template destination-dir
|
||||
```
|
||||
|
||||
Warning: **This will always delete everything in destination-dir**.
|
||||
|
||||
##### Config
|
||||
|
||||
The `bun-create` section of `package.json` is automatically removed from the `package.json` on disk. This lets you add create-only steps without waiting for an extra package to install.
|
||||
|
||||
There are currently two options:
|
||||
|
||||
- `postinstall`
|
||||
- `preinstall`
|
||||
|
||||
They can be an array of strings or one string. An array of steps will be executed in order.
|
||||
|
||||
Here is an example:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@bun-examples/next",
|
||||
"version": "0.0.31",
|
||||
"main": "index.js",
|
||||
"dependencies": {
|
||||
"next": "11.1.2",
|
||||
"react": "^17.0.2",
|
||||
"react-dom": "^17.0.2",
|
||||
"react-is": "^17.0.2"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/react": "^17.0.19",
|
||||
"bun-framework-next": "^0.0.0-21",
|
||||
"typescript": "^4.3.5"
|
||||
},
|
||||
"bun-create": {
|
||||
"postinstall": ["bun bun --use next"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
By default, all commands run inside the environment exposed by the auto-detected npm client. This incurs a significant performance penalty, something like 150ms spent waiting for the npm client to start on each invocation.
|
||||
|
||||
Any command that starts with `"bun "` will be run without npm, relying on the first `bun` binary in `$PATH`.
|
||||
|
||||
##### How `bun create` works
|
||||
|
||||
When you run `bun create ${template} ${destination}`, here's what happens:
|
||||
|
||||
1. GET `registry.npmjs.org/@bun-examples/${template}/latest` and parse it
|
||||
2. GET `registry.npmjs.org/@bun-examples/${template}/-/${template}-${latestVersion}.tgz`
|
||||
3. Decompress & extract `${template}-${latestVersion}.tgz` into `${destination}`
|
||||
|
||||
- If there are files that would overwrite, warn and exit unless `--force` is passed
|
||||
|
||||
4. Parse the `package.json` (again!), update `name` to be `${basename(destination)}`, remove the `bun-create` section from the `package.json` and save updated `package.json` to disk
|
||||
5. Auto-detect the npm client, preferring `pnpm`, `yarn` (v1), and lastly `npm`
|
||||
6. Run any tasks defined in `"bun-create": { "preinstall" }` with the npm client
|
||||
7. Run `${npmClient} install`
|
||||
8. Run any tasks defined in `"bun-create": { "preinstall" }` with the npm client
|
||||
9. Run `git init; git add -A .; git commit -am "Initial Commit";`.
|
||||
|
||||
- Rename `gitignore` to `.gitignore`. NPM automatically removes `.gitignore` files from appearing in packages.
|
||||
|
||||
10. Done
|
||||
|
||||
`misctools/publish-examples.js` publishes all examples to npm.
|
||||
|
||||
### `bun bun`
|
||||
|
||||
Run `bun bun ./path-to.js` to generate a `node_modules.bun` file containing all imported dependencies (recursively).
|
||||
@@ -515,152 +661,6 @@ Is generated like this:
|
||||
|
||||
The implementation details of this module ID hash will vary between versions of Bun. The important part is the metadata contains the module IDs, the package paths, and the package hashes so it shouldn't really matter in practice if other tooling wants to make use of any of this.
|
||||
|
||||
### bun create
|
||||
|
||||
`bun create` is a fast way to create a new project from a template.
|
||||
|
||||
At the time of writing, `bun create react app` runs ~14x faster on my local computer than `yarn create react-app app`. `bun create` currently does no caching (though your npm client does)
|
||||
|
||||
#### Usage
|
||||
|
||||
By default, templates are downloaded from folders inside `examples/` in Bun's GitHub repo. Running `bun create react ./local-path` downloads the `react` folder from `examples/react`.
|
||||
|
||||
Create a new Next.js project:
|
||||
|
||||
```bash
|
||||
bun create next ./app`
|
||||
```
|
||||
|
||||
Create a new React project:
|
||||
|
||||
```bash
|
||||
bun create react ./app
|
||||
```
|
||||
|
||||
To see a list of available templates, run
|
||||
|
||||
```bash
|
||||
bun create
|
||||
```
|
||||
|
||||
##### Local templates
|
||||
|
||||
If you have your own boilerplate you prefer using, copy it into `$HOME/.bun-create/my-boilerplate-name`.
|
||||
|
||||
Before checking Bun's examples folder, `bun create` checks for a local folder matching the input in:
|
||||
|
||||
- `$BUN_CREATE_DIR/`
|
||||
- `$HOME/.bun-create/`
|
||||
- `$(pwd)/.bun-create/`
|
||||
|
||||
If a folder exists in any of those folders with the input, bun will use that instead of a remote template.
|
||||
|
||||
This lets you run:
|
||||
|
||||
```bash
|
||||
bun create my-boilerplate ./app
|
||||
```
|
||||
|
||||
Now your new template should appear when you run:
|
||||
|
||||
```bash
|
||||
bun create
|
||||
```
|
||||
|
||||
Warning: unlike with remote templates, **bun will delete the entire destination folder if it already exists.**
|
||||
|
||||
##### Flags
|
||||
|
||||
| Flag | Description |
|
||||
| ---------------------- | -------------------------------------- |
|
||||
| --npm | Use `npm` for tasks & install |
|
||||
| --yarn | Use `yarn` for tasks & install |
|
||||
| --pnpm | Use `pnpm` for tasks & install |
|
||||
| --force | Overwrite existing files |
|
||||
| --no-install | Skip installing `node_modules` & tasks |
|
||||
| --no-git | Don't initialize a git repository |
|
||||
| ---------------------- | ----------------------------------- |
|
||||
|
||||
By default, `bun create` will cancel if there are existing files it would overwrite and its a remote template. You can pass `--force` to disable this behavior.
|
||||
|
||||
##### Publishing a new template
|
||||
|
||||
Clone this repository and a new folder in `examples/` with your new template. The `package.json` must have a `name` that starts with `@bun-examples/`. Do not worry about publishing it, that will happen automaticallly after the PR is merged.
|
||||
|
||||
Make sure to include a `.gitignore` that includes `node_modules` so that `node_modules` aren't checked in to git when people download the template.
|
||||
|
||||
##### Testing your new template
|
||||
|
||||
To test your new template, add it as a local template or pass the absolute path.
|
||||
|
||||
```bash
|
||||
bun create /path/to/my/new/template destination-dir
|
||||
```
|
||||
|
||||
Warning: **This will always delete everything in destination-dir**.
|
||||
|
||||
##### Config
|
||||
|
||||
The `bun-create` section of package.json is automatically removed from the `package.json` on disk. This lets you add create-only steps without waiting for an extra package to install.
|
||||
|
||||
There are currently two options:
|
||||
|
||||
- `postinstall`
|
||||
- `preinstall`
|
||||
|
||||
They can be an array of strings or one string. An array of steps will be executed in order.
|
||||
|
||||
Here is an example:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@bun-examples/next",
|
||||
"version": "0.0.31",
|
||||
"main": "index.js",
|
||||
"dependencies": {
|
||||
"next": "11.1.2",
|
||||
"react": "^17.0.2",
|
||||
"react-dom": "^17.0.2",
|
||||
"react-is": "^17.0.2"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/react": "^17.0.19",
|
||||
"bun-framework-next": "^0.0.0-21",
|
||||
"typescript": "^4.3.5"
|
||||
},
|
||||
"bun-create": {
|
||||
"postinstall": ["bun bun --use next"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
By default, all commands run inside the environment exposed by the auto-detected npm client. This incurs a significant performance penalty, something like 150ms spent waiting for the npm client to start on each invocation.
|
||||
|
||||
Any command that starts with `"bun "` will be run without npm, relying on the first `bun` binary in `$PATH`.
|
||||
|
||||
##### How `bun create` works
|
||||
|
||||
When you run `bun create ${template} ${destination}`, here's what happens:
|
||||
|
||||
1. GET `registry.npmjs.org/@bun-examples/${template}/latest` and parse it
|
||||
2. GET `registry.npmjs.org/@bun-examples/${template}/-/${template}-${latestVersion}.tgz`
|
||||
3. Decompress & extract `${template}-${latestVersion}.tgz` into `${destination}`
|
||||
|
||||
- If there are files that would overwrite, warn and exit unless `--force` is passed
|
||||
|
||||
4. Parse the `package.json` (again!), update `name` to be `${basename(destination)}`, remove the `bun-create` section from the `package.json` and save updated `package.json` to disk
|
||||
5. Auto-detect the npm client, preferring `pnpm`, `yarn` (v1), and lastly `npm`
|
||||
6. Run any tasks defined in `"bun-create": { "preinstall" }` with the npm client
|
||||
7. Run `${npmClient} install`
|
||||
8. Run any tasks defined in `"bun-create": { "preinstall" }` with the npm client
|
||||
9. Run `git init; git add -A .; git commit -am "Initial Commit";`.
|
||||
|
||||
- Rename `gitignore` to `.gitignore`. NPM automatically removes `.gitignore` files from appearing in packages.
|
||||
|
||||
10. Done
|
||||
|
||||
`../misctools/publish-examples.js` publishes all examples to npm.
|
||||
|
||||
### Environment variables
|
||||
|
||||
- `GOMAXPROCS`: For `bun bun`, this sets the maximum number of threads to use. If you're experiencing an issue with `bun bun`, try setting `GOMAXPROCS=1` to force bun to run single-threaded
|
||||
|
||||
Reference in New Issue
Block a user