Add doc explaining bun-create

1 files changed, 58 insertions, 1 deletions

diff --git a/examples/bun-create.md b/examples/bun-create.md
index 28ed72f7b..68119ed0d 100644
--- a/examples/bun-create.md
+++ b/examples/bun-create.md
@@ -1,4 +1,61 @@
 # `bun create`
 
-This folder 
+## Config
 
+The `bun-create` section of package.json is automatically removed from the final output. This lets you add create-only steps without installing an extra package.
+
+There are currently two options:
+
+- `postinstall`
+- `preinstall`
+
+They can be an array of strings or one string. An array of strings will be executed one after another.
+
+Here are examples:
+
+```
+{
+  "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 wasted on waiting for the npm client to start on each invocation.
+
+Any command that starts with `"bun "` will be run without npm.
+
+## How it 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}`
+   3a. 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";`.
+   8a. Rename `gitignore` to `.gitignore`. NPM automatically removes `.gitignore` files from appearing in packages.
+10. Done
+
+`../misctools/publish-examples.js` publishes all examples to npm.