aboutsummaryrefslogtreecommitdiff
path: root/docs/guides
diff options
context:
space:
mode:
authorGravatar Colin McDonnell <colinmcd94@gmail.com> 2023-09-13 20:43:39 -0700
committerGravatar GitHub <noreply@github.com> 2023-09-13 20:43:39 -0700
commitc99caccdb2e1bb961b13766ec7ebb9907763e364 (patch)
treecbc65806656c2b2765666e96a168f5613adf9bb4 /docs/guides
parent22f14129e5f8e0328b200ce3a8573dbd7c9562c4 (diff)
downloadbun-c99caccdb2e1bb961b13766ec7ebb9907763e364.tar.gz
bun-c99caccdb2e1bb961b13766ec7ebb9907763e364.tar.zst
bun-c99caccdb2e1bb961b13766ec7ebb9907763e364.zip
More docs & helptext cleanup (#5229)
* wip * Flesh out resolution docs * Polish * More * WIP * WIP * WIP * Document --watch
Diffstat (limited to 'docs/guides')
-rw-r--r--docs/guides/ecosystem/nextjs.md13
-rw-r--r--docs/guides/install/registry-scope.md6
-rw-r--r--docs/guides/install/workspaces.md4
-rw-r--r--docs/guides/runtime/typescript.md69
4 files changed, 88 insertions, 4 deletions
diff --git a/docs/guides/ecosystem/nextjs.md b/docs/guides/ecosystem/nextjs.md
index a455eb23e..4d3be8cfc 100644
--- a/docs/guides/ecosystem/nextjs.md
+++ b/docs/guides/ecosystem/nextjs.md
@@ -3,7 +3,7 @@ name: Build an app with Next.js and Bun
---
{% callout %}
-Next.js currently relies on Node.js APIs that Bun does not yet implement. The guide below uses Bun to initialize a project and install dependencies, but it uses Node.js to run the dev server.
+The Next.js [App Router](https://nextjs.org/docs/app) currently relies on Node.js APIs that Bun does not yet implement. The guide below uses Bun to initialize a project and install dependencies, but it uses Node.js to run the dev server.
{% /callout %}
---
@@ -23,7 +23,16 @@ Creating a new Next.js app in /path/to/my-app.
---
-To start the dev server, run `bun run dev` from the project root.
+To start the dev server with Bun, run `bun --bun run dev` from the project root.
+
+```sh
+$ cd my-app
+$ bun --bun run dev
+```
+
+---
+
+To run the dev server with Node.js instead, omit `--bun`.
```sh
$ cd my-app
diff --git a/docs/guides/install/registry-scope.md b/docs/guides/install/registry-scope.md
index 48f7dee79..68d8cf942 100644
--- a/docs/guides/install/registry-scope.md
+++ b/docs/guides/install/registry-scope.md
@@ -11,7 +11,11 @@ Bun does not read `.npmrc` files; instead private registries are configured via
# as an object with username/password
# you can reference environment variables
-"@myorg2" = { username = "myusername", password = "$npm_pass", url = "https://registry.myorg.com/" }
+"@myorg2" = {
+ username = "myusername",
+ password = "$npm_pass",
+ url = "https://registry.myorg.com/"
+}
# as an object with token
"@myorg3" = { token = "$npm_token", url = "https://registry.myorg.com/" }
diff --git a/docs/guides/install/workspaces.md b/docs/guides/install/workspaces.md
index f87c1e337..4628d6aaa 100644
--- a/docs/guides/install/workspaces.md
+++ b/docs/guides/install/workspaces.md
@@ -4,6 +4,8 @@ name: Configuring a monorepo using workspaces
Bun's package manager supports npm `"workspaces"`. This allows you to split a codebase into multiple distinct "packages" that live in the same repository, can depend on each other, and (when possible) share a `node_modules` directory.
+Clone [this sample project](https://github.com/colinhacks/bun-workspaces) to experiment with workspaces.
+
---
The root `package.json` should not contain any `"dependencies"`, `"devDependencies"`, etc. Each individual package should be self-contained and declare its own dependencies. Similarly, it's conventional to declare `"private": true` to avoid accidentally publishing the root package to `npm`.
@@ -37,7 +39,7 @@ It's common to place all packages in a `packages` directory. The `"workspaces"`
To add one workspace as a dependency of another, modify its `package.json`. Here we're adding `stuff-a` as a dependency of `stuff-b`.
-```json#packages/stuff-b/package.json
+```json-diff#packages/stuff-b/package.json
{
"name": "stuff-b",
"dependencies": {
diff --git a/docs/guides/runtime/typescript.md b/docs/guides/runtime/typescript.md
new file mode 100644
index 000000000..f6afe02c1
--- /dev/null
+++ b/docs/guides/runtime/typescript.md
@@ -0,0 +1,69 @@
+---
+name: Install TypeScript declarations for Bun
+---
+
+To install TypeScript definitions for Bun's built-in APIs in your project, install `bun-types`.
+
+```sh
+$ bun add -d bun-types # dev dependency
+```
+
+---
+
+Then include `"bun-types"` in the `compilerOptions.types` in your `tsconfig.json`:
+
+```json-diff
+ {
+ "compilerOptions": {
++ "types": ["bun-types"]
+ }
+ }
+```
+
+---
+
+Unfortunately, setting a value for `"types"` means that TypeScript will ignore other global type definitions, including `lib: ["dom"]`. If you need to add DOM types into your project, add the following [triple-slash directives](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html) at the top of any TypeScript file in your project.
+
+```ts
+/// <reference lib="dom" />
+/// <reference lib="dom.iterable" />
+```
+
+---
+
+Below is the full set of recommended `compilerOptions` for a Bun project. With this `tsconfig.json`, you can use top-level await, extensioned or extensionless imports, and JSX.
+
+```jsonc
+{
+ "compilerOptions": {
+ // add Bun type definitions
+ "types": ["bun-types"],
+
+ // enable latest features
+ "lib": ["esnext"],
+ "module": "esnext",
+ "target": "esnext",
+
+ // if TS 5.x+
+ "moduleResolution": "bundler",
+ "noEmit": true,
+ "allowImportingTsExtensions": true,
+ "moduleDetection": "force",
+ // if TS 4.x or earlier
+ // "moduleResolution": "nodenext",
+
+ "jsx": "react-jsx", // support JSX
+ "allowJs": true, // allow importing `.js` from `.ts`
+ "esModuleInterop": true, // allow default imports for CommonJS modules
+
+ // best practices
+ "strict": true,
+ "forceConsistentCasingInFileNames": true,
+ "skipLibCheck": true
+ }
+}
+```
+
+---
+
+Refer to [Ecosystem > TypeScript](/docs/runtime/typescript) for a complete guide to TypeScript support in Bun.