diff options
author | 2023-09-13 20:43:39 -0700 | |
---|---|---|
committer | 2023-09-13 20:43:39 -0700 | |
commit | c99caccdb2e1bb961b13766ec7ebb9907763e364 (patch) | |
tree | cbc65806656c2b2765666e96a168f5613adf9bb4 /docs/guides | |
parent | 22f14129e5f8e0328b200ce3a8573dbd7c9562c4 (diff) | |
download | bun-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.md | 13 | ||||
-rw-r--r-- | docs/guides/install/registry-scope.md | 6 | ||||
-rw-r--r-- | docs/guides/install/workspaces.md | 4 | ||||
-rw-r--r-- | docs/guides/runtime/typescript.md | 69 |
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. |