diff --git a/runtime/getting_started/command_line_interface.md b/runtime/getting_started/command_line_interface.md index bd980e290..143d8c018 100644 --- a/runtime/getting_started/command_line_interface.md +++ b/runtime/getting_started/command_line_interface.md @@ -1,6 +1,6 @@ --- title: Command line interface -description: "A comprehensive guide to using Deno's command-line interface (CLI). Learn about running scripts, managing permissions, using watch mode, and configuring Deno's runtime behavior through command-line flags and options." +description: "An overview of Deno's command-line interface: running scripts, common flags, and key subcommands." oldUrl: - /manual/getting_started/command_line_interface - /runtime/manual/getting_started/command_line_interface/ @@ -8,227 +8,93 @@ oldUrl: - /runtime/manual/tools/ --- -Deno is a command line program. The Deno command line interface (CLI) can be -used to run scripts, manage dependencies, and even compile your code into -standalone executables. You may be familiar with some simple commands having -followed the examples thus far. This page will provide a more detailed overview -of the Deno CLI. - -The Deno CLI has a number of subcommands (like `run`, `init` and `test`, etc.). -They are used to perform different tasks within the Deno runtime environment. -Each subcommand has its own set of flags and options (eg --version) that can be -used to customize its behavior. - -You can view all of the available commands and flags by running the `deno help` -subcommand in your terminal, or using the `-h` or `--help` flags. - -Check out the [CLI reference guide](/runtime/reference/cli/) for a further -documentation on all the subcommands and flags available. We'll take a look at a -few commands in a bit more detail below to see how they can be used and -configured. - -## An example subcommand - `deno run` - -You can run a local TypeScript or JavaScript file by specifying its path -relative to the current working directory: +The Deno CLI lets you run scripts, manage dependencies, run tests, format code, +and more. You can view all available commands by running: ```shell -deno run main.ts +deno help ``` -Deno supports running scripts directly from URLs. This is particularly useful -for quickly testing or running code without downloading it first: +For detailed documentation on every subcommand and flag, see the +[CLI reference guide](/runtime/reference/cli/). -```shell -deno run https://docs.deno.com/examples/scripts/hello_world.ts -``` +## Running scripts -You can also run a script by piping it through standard input. This is useful -for integrating with other command-line tools or dynamically generating scripts: +Run a local TypeScript or JavaScript file: ```shell -cat main.ts | deno run - -``` - -## Passing script arguments - -Script arguments are additional parameters you can pass to your script when -running it from the command line. These arguments can be used to customize the -behavior of your program based on the input provided at runtime. Arguments -should be passed **after** the script name. - -To test this out we can make a script that will log the arguments passed to it: - -```ts title="main.ts" -console.log(Deno.args); +deno run main.ts ``` -When we run that script and pass it some arguments it will log them to the -console: +You can also pipe code from stdin: ```shell -$ deno run main.ts arg1 arg2 arg3 -[ "arg1", "arg2", "arg3" ] +cat main.ts | deno run - ``` -## Argument and flag ordering +## Permissions -_Note that anything passed after the script name will be passed as a script -argument and not consumed as a Deno runtime flag._ This leads to the following -pitfall: +By default, Deno runs programs in a sandbox without access to disk, network, or +environment. Use `--allow-*` flags to grant access: ```shell -# Good. We grant net permission to net_client.ts. -deno run --allow-net net_client.ts +# Allow network and file read access +deno run --allow-net --allow-read server.ts -# Bad! --allow-net was passed to Deno.args, throws a net permission error. -deno run net_client.ts --allow-net +# Grant all permissions (not recommended for production) +deno run -A server.ts ``` -## Common flags - -Some flags can be used with multiple related subcommands. We discuss these -below. +Learn more about [permissions and security](/runtime/fundamentals/security/). -### Watch mode - -You can supply the `--watch` flag to `deno run`, `deno test`, and `deno fmt` to -enable the built-in file watcher. The watcher enables automatic reloading of -your application whenever changes are detected in the source files. This is -particularly useful during development, as it allows you to see the effects of -your changes immediately without manually restarting the application. - -The files that are watched will depend on the subcommand used: - -- for `deno run` and `deno test` the entrypoint, and all local files that the - entrypoint statically imports will be watched. -- for `deno fmt` all local files and directories specified as command line - arguments (or the working directory if no specific files/directories is - passed) are watched. - -```shell -deno run --watch main.ts -deno test --watch -deno fmt --watch -``` +## Script arguments -You can exclude paths or patterns from watching by providing the -`--watch-exclude` flag. The syntax is `--watch-exclude=path1,path2`. For -example: +Arguments passed **after** the script name are available via `Deno.args`: ```shell -deno run --watch --watch-exclude=file1.ts,file2.ts main.ts +$ deno run main.ts arg1 arg2 arg3 +[ "arg1", "arg2", "arg3" ] ``` -This will exclude file1.ts and file2.ts from being watched. +:::caution -To exclude a pattern, remember to surround it in quotes to prevent your shell -from expanding the glob: +Deno flags must come _before_ the script name. Anything after the script name is +treated as a script argument, not a Deno flag: ```shell -deno run --watch --watch-exclude='*.js' main.ts -``` - -### Hot Module Replacement mode - -You can use `--watch-hmr` flag with `deno run` to enable the hot module -replacement mode. Instead of restarting the program, the runtime will try to -update the program in-place. If updating in-place fails, the program will still -be restarted. - -```sh -deno run --watch-hmr main.ts -``` - -When a hot module replacement is triggered, the runtime will dispatch a -`CustomEvent` of type `hmr` that will include `path` property in its `detail` -object. You can listen for this event and perform any additional logic that you -need to do when a module is updated (eg. notify a browser over a WebSocket -connection). - -```ts -addEventListener("hmr", (e) => { - console.log("HMR triggered", e.detail.path); -}); -``` - -### Integrity flags (lock files) - -Affect commands which can download resources to the cache: `deno install`, -`deno run`, `deno test`, `deno doc`, and `deno compile`. +# Good β€” grants net permission +deno run --allow-net server.ts -```sh ---lock Check the specified lock file ---frozen[=] Error out if lockfile is out of date +# Bad β€” --allow-net is passed to Deno.args instead +deno run server.ts --allow-net ``` -Find out more about these -[here](/runtime/fundamentals/modules/#integrity-checking-and-lock-files). +::: -### Cache and compilation flags +## Watch mode -Affect commands which can populate the cache: `deno install`, `deno run`, -`deno test`, `deno doc`, and `deno compile`. As well as the flags above, this -includes those which affect module resolution, compilation configuration etc. - -```sh ---config Load configuration file ---import-map Load import map file ---no-remote Do not resolve remote modules ---reload= Reload source code cache (recompile TypeScript) -``` - -### Runtime flags - -Affect commands which execute user code: `deno run` and `deno test`. These -include all of the above as well as the following. - -### Type checking flags - -You can type-check your code (without executing it) using the command: +Use `--watch` to automatically restart on file changes during development: ```shell -> deno check main.ts -``` - -You can also type-check your code before execution by using the `--check` -argument to deno run: - -```shell -> deno run --check main.ts +deno run --watch server.ts +deno test --watch ``` -This flag affects `deno run` and `deno eval`. The following table describes the -type-checking behavior of various subcommands. Here "Local" means that only -errors from local code will induce type-errors, modules imported from https URLs -(remote) may have type errors that are not reported. (To turn on type-checking -for all modules, use `--check=all`.) - -| Subcommand | Type checking mode | -| -------------- | ------------------ | -| `deno bench` | πŸ“ Local | -| `deno check` | πŸ“ Local | -| `deno compile` | πŸ“ Local | -| `deno eval` | ❌ None | -| `deno repl` | ❌ None | -| `deno run` | ❌ None | -| `deno test` | πŸ“ Local | - -### Permission flags - -These are listed [here](/runtime/fundamentals/security/). - -### Other runtime flags - -More flags which affect the execution environment. - -```sh ---cached-only Require that remote dependencies are already cached ---inspect= activate inspector on host:port ... ---inspect-brk= activate inspector on host:port and break at ... ---inspect-wait= activate inspector on host:port and wait for ... ---location Value of 'globalThis.location' used by some web APIs ---prompt Fallback to prompt if required permission wasn't passed ---seed Seed Math.random() ---v8-flags= Set V8 command line options. For help: ... -``` +## Key subcommands + +| Command | Description | +| ---------------------------------------------------- | ------------------------------------------------------------------------------------ | +| [`deno run`](/runtime/reference/cli/run/) | Execute a script | +| [`deno serve`](/runtime/reference/cli/serve/) | Run an HTTP server | +| [`deno test`](/runtime/reference/cli/test/) | Run tests | +| [`deno fmt`](/runtime/reference/cli/fmt/) | Format source code | +| [`deno lint`](/runtime/reference/cli/lint/) | Lint source code | +| [`deno check`](/runtime/reference/cli/check/) | Type-check without running | +| [`deno add`](/runtime/reference/cli/add/) | Add a dependency to `deno.json` | +| [`deno install`](/runtime/reference/cli/install/) | Install dependencies | +| [`deno compile`](/runtime/reference/cli/compile/) | Compile to a standalone binary | +| [`deno task`](/runtime/reference/cli/task/) | Run a task defined in `deno.json` | +| [`deno doc`](/runtime/reference/cli/doc/) | Generate documentation | + +Each command has its own flags β€” run `deno --help` for details, or +browse the [CLI reference](/runtime/reference/cli/). diff --git a/runtime/getting_started/first_project.md b/runtime/getting_started/first_project.md index 72a0eaaea..5115941b5 100644 --- a/runtime/getting_started/first_project.md +++ b/runtime/getting_started/first_project.md @@ -1,71 +1,175 @@ --- title: Making a Deno project -description: "Step-by-step guide to creating your first Deno project. Learn how to initialize a project, understand the basic file structure, run TypeScript code, and execute tests using Deno's built-in test runner." +description: "Step-by-step guide to creating your first Deno project. Learn how to initialize a project, build an HTTP server, add dependencies, and run tests." oldUrl: /runtime/manual/getting_started/first_steps/ --- -Deno has many [built in tools](/runtime/reference/cli/) to make your development -experience as smooth as possible. One of these tools is the -[project initializer](/runtime/reference/cli/init), which creates a new Deno -project with a basic file structure and configuration. +This guide walks you through creating a Deno project from scratch, building a +small HTTP server, adding a dependency, and running tests. -While you are welcome to use JavaScript, Deno has built-in support for -[TypeScript](https://www.typescriptlang.org/) as well, so we'll be using -TypeScript in this guide. If you'd prefer to use JavaScript, you can rename the -files to `.js` and remove the type annotations. - -## Initialize a new project - -To initialize a new Deno project, run the following command in your terminal: +## Initialize a project ```bash deno init my_project +cd my_project ``` -This will create a new directory called `my_project` with the following -structure: +This creates a directory with three files: ```plaintext my_project β”œβ”€β”€ deno.json -β”œβ”€β”€ main_test.ts -└── main.ts +β”œβ”€β”€ main.ts +└── main_test.ts ``` -A `deno.json` file is created to -[configure your project](/runtime/fundamentals/configuration/), and two -TypeScript files are created; `main.ts` and `main_test.ts`. The `main.ts` file -is where you'll write your application code, on initial creation it will contain -a simple program which adds two numbers together. The `main_test.ts` file is -where you can write tests, initially it will contain a test for your addition -program. - -## Run your project - -You can run this program with the following command: +Run it to make sure everything works: ```bash $ deno main.ts Add 2 + 3 = 5 ``` -## Run your tests +## Build a server + +Replace the contents of `main.ts` with a simple HTTP server: + +```ts title="main.ts" +Deno.serve((_req) => { + return new Response("Hello, world!"); +}); +``` -Deno has a [built in test runner](/runtime/fundamentals/testing/). You can write -tests for your code and run them with the `deno test` command. Run the tests in -your new project with: +Run it: ```bash -$ deno test -running 1 test from ./main_test.ts -addTest ... ok (1ms) +$ deno run --allow-net main.ts +Listening on http://0.0.0.0:8000/ +``` + +Open [http://localhost:8000](http://localhost:8000) in your browser and you'll +see "Hello, world!". + +## Add routing + +Let's make it more interesting. Update `main.ts` to handle different routes: + +```ts title="main.ts" +Deno.serve((req) => { + const url = new URL(req.url); -ok | 1 passed | 0 failed (3ms) + if (url.pathname === "/") { + return new Response("Home"); + } + + if (url.pathname === "/about") { + return new Response("About page"); + } + + return new Response("Not found", { status: 404 }); +}); +``` + +Restart the server and try +[http://localhost:8000/about](http://localhost:8000/about). + +:::tip + +Use `deno run --watch --allow-net main.ts` to automatically restart the server +when you save changes. + +::: + +## Add a dependency + +Install a package using `deno add`. Let's add +[`zod`](https://www.npmjs.com/package/zod) from npm to validate query +parameters: + +```bash +$ deno add npm:zod +Add zod - npm:zod@4.3.6 ``` -Now that you have a basic project set up you can start building your -application. Check out our [examples and tutorials](/examples/) for more ideas -on what to build with Deno. +This updates your `deno.json` automatically. Now update `main.ts` to use it: + +```ts title="main.ts" +import { z } from "zod"; + +const GreetParams = z.object({ + name: z.string().min(1), +}); + +Deno.serve((req) => { + const url = new URL(req.url); + + if (url.pathname === "/") { + return new Response("Home"); + } + + if (url.pathname === "/greet") { + const result = GreetParams.safeParse({ + name: url.searchParams.get("name"), + }); + + if (!result.success) { + return new Response("Invalid params: name is required", { status: 400 }); + } + + return new Response(`Hello, ${result.data.name}!`); + } + + return new Response("Not found", { status: 404 }); +}); +``` + +Restart the server and try +[http://localhost:8000/greet?name=Alice](http://localhost:8000/greet?name=Alice). +Try it without the `name` parameter to see the validation error. + +## Write a test + +Replace the contents of `main_test.ts` with a test for your server: + +```ts title="main_test.ts" +import { assertEquals } from "@std/assert"; + +Deno.test("home route returns 200", async () => { + const server = Deno.serve( + { port: 9000, onListen() {} }, + (req) => { + const url = new URL(req.url); + if (url.pathname === "/") { + return new Response("Home"); + } + return new Response("Not found", { status: 404 }); + }, + ); + + const res = await fetch("http://localhost:9000/"); + assertEquals(res.status, 200); + assertEquals(await res.text(), "Home"); + + await server.shutdown(); +}); +``` + +Run the tests: + +```bash +$ deno test --allow-net +running 1 test from ./main_test.ts +home route returns 200 ... ok (5ms) + +ok | 1 passed | 0 failed (12ms) +``` + +## Next steps + +You now have a working project with an HTTP server, a dependency, and tests. +From here you can: -You can -[learn more about using TypeScript in Deno here](/runtime/fundamentals/typescript). +- Browse [examples and tutorials](/examples/) for more ideas +- Learn about [modules and dependencies](/runtime/fundamentals/modules/) +- Explore the [Deno Standard Library](/runtime/reference/std/) +- Set up your [editor/IDE](/runtime/getting_started/setup_your_environment/) diff --git a/runtime/getting_started/installation.md b/runtime/getting_started/installation.md index 8dd639b26..eb298e530 100644 --- a/runtime/getting_started/installation.md +++ b/runtime/getting_started/installation.md @@ -1,244 +1,156 @@ --- title: Installation -description: "A Guide to installing Deno on different operating systems. Includes instructions for Windows, macOS, and Linux using various package managers, manual installation methods, and Docker containers." +description: "A guide to installing Deno on macOS, Windows, and Linux." oldUrl: - /runtime/manual/fundamentals/installation - /runtime/manual/getting_started/installation - /runtime/fundamentals/installation --- -Deno works on macOS, Linux, and Windows. Deno is a single binary executable. It -has no external dependencies. On macOS, both M1 (arm64) and Intel (x64) -executables are provided. On Windows, both ARM64 and x64 are supported. On -Linux, only x64 is supported. +Deno ships as a single binary executable with no external dependencies. It works +on macOS (arm64 and x64), Windows (ARM64 and x64), and Linux (x64). -## Download and install - -[deno_install](https://github.com/denoland/deno_install) provides convenience -scripts to download and install the binary. +## Install -Using Shell: - ```shell curl -fsSL https://deno.land/install.sh | sh ``` -Using [npm](https://npmjs.com/package/deno): - -```shell -npm install -g deno -``` - -> The startup time of the Deno command gets affected if it's installed -> via npm. We recommend the shell install script for better performance. - -Using [Homebrew](https://formulae.brew.sh/formula/deno): +Or using [Homebrew](https://formulae.brew.sh/formula/deno): ```shell brew install deno ``` -Using [MacPorts](https://ports.macports.org/port/deno/): - -```shell -sudo port install deno -``` - -Using [Nix](https://nixos.org/download.html): - -```shell -nix-shell -p deno -``` - -Using [asdf](https://asdf-vm.com/): - -```shell -asdf plugin add deno https://github.com/asdf-community/asdf-deno.git - -# Download and install the latest version of Deno -asdf install deno latest - -# To set as the default version of Deno globally -asdf set -u deno latest - -# To set as the default version of Deno locally (current project only) -asdf set deno latest -``` - -Using [vfox](https://vfox.dev/): - -```shell -vfox add deno - -# Download and install the latest version of Deno -vfox install deno@latest - -# To set the version of Deno globally -vfox use --global deno -``` - -**NOTE:** Deno requires Windows 10 version 1709, or Windows Server 2016 version -1709 and up, due to requiring -[IsWow64Process2](https://learn.microsoft.com/en-us/windows/win32/api/wow64apiset/nf-wow64apiset-iswow64process2). - -Using PowerShell (Windows): +Using PowerShell: ```powershell irm https://deno.land/install.ps1 | iex ``` -Using [npm](https://npmjs.com/package/deno): - -```shell -npm install -g deno -``` - -> The startup time of the Deno command gets affected if it's installed -> via npm. We recommend the PowerShell install script for better -> performance. - -Using [Scoop](https://scoop.sh/): +Or using [Scoop](https://scoop.sh/): ```shell scoop install deno ``` -Using [Chocolatey](https://chocolatey.org/packages/deno): - -```shell -choco install deno -``` - -Using [Winget](https://github.com/microsoft/winget-cli): +Or using [Winget](https://github.com/microsoft/winget-cli): ```shell winget install DenoLand.Deno ``` -Using [vfox](https://vfox.dev/): - -```shell -vfox add deno +:::note -# Download and install the latest version of Deno -vfox install deno@latest +Deno requires Windows 10 version 1709 or later. -# To set the version of Deno globally -vfox use --global deno -``` +::: -Using Shell: - ```shell curl -fsSL https://deno.land/install.sh | sh ``` -Using [npm](https://npmjs.com/package/deno): - -```shell -npm install -g deno -``` - -> The startup time of the Deno command gets affected if it's installed -> via npm. We recommend the shell install script for better performance. + + -Using [Nix](https://nixos.org/download.html): +Verify the installation: ```shell -nix-shell -p deno +deno --version ``` -Using [asdf](https://asdf-vm.com/): +:::tip -```shell -asdf plugin add deno https://github.com/asdf-community/asdf-deno.git +Deno can also be installed via [npm](https://npmjs.com/package/deno) +(`npm install -g deno`), though the shell install script is recommended for +better startup performance. -# Download and install the latest version of Deno -asdf install deno latest +::: -# To set as the default version of Deno globally -asdf set -u deno latest +
+More installation methods -# To set as the default version of Deno locally (current project only) -asdf set deno latest -``` +**macOS:** -Using [vfox](https://vfox.dev/): +- [MacPorts](https://ports.macports.org/port/deno/): `sudo port install deno` +- [Nix](https://nixos.org/download.html): `nix-shell -p deno` +- [asdf](https://asdf-vm.com/): `asdf plugin add deno https://github.com/asdf-community/asdf-deno.git && asdf install deno latest && asdf set -u deno latest` +- [vfox](https://vfox.dev/): `vfox add deno && vfox install deno@latest` -```shell -vfox add deno +**Windows:** -# Download and install the latest version of Deno -vfox install deno@latest +- [Chocolatey](https://chocolatey.org/packages/deno): `choco install deno` -# To set the version of Deno globally -vfox use --global deno -``` +**Linux:** - - +- [Nix](https://nixos.org/download.html): `nix-shell -p deno` +- [asdf](https://asdf-vm.com/): `asdf plugin add deno https://github.com/asdf-community/asdf-deno.git && asdf install deno latest && asdf set -u deno latest` +- [vfox](https://vfox.dev/): `vfox add deno && vfox install deno@latest` -You can also build and install from source using -[Cargo](https://crates.io/crates/deno): +**From source:** ```shell cargo install deno --locked ``` -Deno binaries can also be installed manually, by downloading a zip file at +**Manual download:** + +Deno binaries can be downloaded directly from [github.com/denoland/deno/releases](https://github.com/denoland/deno/releases). -These packages contain just a single executable file. You will have to set the -executable bit on macOS and Linux. + +
## Docker -For more information and instructions on the official Docker images: -[https://github.com/denoland/deno_docker](https://github.com/denoland/deno_docker) +Official images are available on +[Docker Hub](https://hub.docker.com/r/denoland/deno) and +[GHCR](https://github.com/denoland/deno/pkgs/container/deno) in several +variants: -## Testing your installation +| Tag | Base | +| --- | --- | +| `denoland/deno:debian` | Debian (default) | +| `denoland/deno:ubuntu` | Ubuntu | +| `denoland/deno:alpine` | Alpine Linux | +| `denoland/deno:distroless` | Distroless | +| `denoland/deno:bin` | Binary only | -To test your installation, run `deno --version`. If this prints the Deno version -to the console the installation was successful. +All tags are also available with a version prefix, e.g. `denoland/deno:2.3.1`. -Use `deno help` to see help text documenting Deno's flags and usage. Get a -detailed guide on the CLI -[here](/runtime/getting_started/command_line_interface/). +A typical `Dockerfile`: -## Updating +```dockerfile +FROM denoland/deno:debian +WORKDIR /app +COPY . . +RUN deno install +CMD ["deno", "run", "--allow-net", "main.ts"] +``` -To update a previously installed version of Deno, you can run: +See the [deno_docker repo](https://github.com/denoland/deno_docker) for more +details. -```shell -deno upgrade -``` +## Updating -Or using [Winget](https://github.com/microsoft/winget-cli) (Windows): +To update to the latest version: ```shell -winget upgrade DenoLand.Deno +deno upgrade ``` -This will fetch the latest release from -[github.com/denoland/deno/releases](https://github.com/denoland/deno/releases), -unzip it, and replace your current executable with it. - -You can also use this utility to install a specific version of Deno: +To install a specific version: ```shell -deno upgrade --version 1.0.1 +deno upgrade --version 2.3.1 ``` -## Building from source - -Information about how to build from source can be found in the -[`Building from source`](https://github.com/denoland/deno/blob/main/.github/CONTRIBUTING.md#building-from-source) -guide. +On Windows, `winget upgrade DenoLand.Deno` also works. diff --git a/runtime/getting_started/setup_your_environment.md b/runtime/getting_started/setup_your_environment.md index 38d4a1bd0..d57b7c9b9 100644 --- a/runtime/getting_started/setup_your_environment.md +++ b/runtime/getting_started/setup_your_environment.md @@ -1,39 +1,24 @@ --- title: "Set up your environment" -description: "A guide to setting up your development environment for Deno. Learn how to configure popular editors like VS Code, set up language server support, and enable shell completions for better productivity." +description: "A guide to setting up your development environment for Deno. Learn how to configure VS Code, JetBrains, and other editors with Deno's built-in language server." oldUrl: /runtime/manual/getting_started/setup_your_environment/ --- -Deno comes with many of the tools that are commonly needed for developing -applications, including a full -[language server (LSP)](/runtime/reference/cli/lsp/) to help power your IDE of -choice. This page will help you set up your environment to get the most out of -Deno while you are developing. +Deno includes a full +[language server (LSP)](/runtime/reference/cli/lsp/) that provides autocomplete, +go-to-definition, diagnostics, formatting, and more in your editor. -We'll cover: +## Visual Studio Code -- How to use Deno with your favorite editor/IDE -- How to use Deno with AI coding assistants -- How to generate shell completions - -## Setting up your editor/IDE - -### Visual Studio Code - -If you haven’t already, download and install Visual Studio Code from the -[official website](https://code.visualstudio.com/). - -In the Extensions tab, search for "Deno" and install the -[extension by Denoland](https://marketplace.visualstudio.com/items?itemName=denoland.vscode-deno). - -Next, open the Command Palette by pressing `Ctrl+Shift+P` and type -`Deno: Initialize Workspace Configuration`. Select this option to configure Deno -for your workspace. +1. Install the + [Deno extension](https://marketplace.visualstudio.com/items?itemName=denoland.vscode-deno) + from the Extensions panel. +2. Open the Command Palette (`Ctrl+Shift+P`) and run + **Deno: Initialize Workspace Configuration**. ![The VSCode command palette with the Deno: Initialize Workspace Configuration option selected.](./images/vscode-setup.png) -A file called `.vscode/settings.json` will be created in your workspace with the -following configuration: +This creates a `.vscode/settings.json` with: ```json { @@ -41,11 +26,21 @@ following configuration: } ``` -That’s it! You’ve successfully set up your developer environment for Deno using -VSCode. You will now get all the benefits of Deno’s LSP, including IntelliSense, -code formatting, linting, and more. +You now have IntelliSense, formatting, linting, and more powered by Deno's LSP. + +## JetBrains IDEs -### Skills for AI assistants +Install the official Deno plugin: **File > Settings > Plugins**, search for +"Deno". + +Then enable it: **File > Settings > Languages & Frameworks > JavaScript +Runtime**, set **Preferred Runtime** to **Deno**. + +See the +[JetBrains blog post](https://blog.jetbrains.com/webstorm/2020/06/deno-support-in-jetbrains-ides/) +for more details. + +## Skills for AI assistants Deno provides official **skills** β€” specialized knowledge packs that give AI coding assistants (such as Claude, GitHub Copilot, Cursor, and others) accurate, @@ -73,44 +68,18 @@ Available skills include: - **deno-expert** β€” advanced Deno patterns for code review and debugging - **deno-sandbox** β€” executing untrusted code safely with `@deno/sandbox` -### JetBrains IDEs - -To install the Deno Plugin, open your IDE and go to **File** > **Settings**. -Navigate to **Plugins** and search for `Deno`. Install the official Deno plugin. - -![The WebStorm plugins settings](./images/webstorm_setup.png) +## Other editors -To configure the Plugin, go to **File** > **Settings** again. Navigate to -**Languages & Frameworks** > **JavaScript Runtime**. Switch **Preferred -Runtime** to **Deno**. Under **Deno**, specify the path to the Deno executable -(if it has not been auto-detected). +
+Vim / Neovim -Check out -[this blog post](https://blog.jetbrains.com/webstorm/2020/06/deno-support-in-jetbrains-ides/) -to learn more about how to get started with Deno in Jetbrains IDEs. +### Neovim 0.6+ (built-in LSP) -### Vim/Neovim via plugins - -Deno is well-supported on both [Vim](https://www.vim.org/) and -[Neovim](https://neovim.io/) via -[coc.nvim](https://github.com/neoclide/coc.nvim), -[vim-easycomplete](https://github.com/jayli/vim-easycomplete), -[ALE](https://github.com/dense-analysis/ale) and -[vim-lsp](https://github.com/prabirshrestha/vim-lsp). coc.nvim offers plugins to -integrate to the Deno language server while ALE supports it _out of the box_. - -### Neovim 0.6+ using the built-in language server - -To use the Deno language server install -[nvim-lspconfig](https://github.com/neovim/nvim-lspconfig/) and follow the -instructions to enable the -[supplied Deno configuration](https://github.com/neovim/nvim-lspconfig/blob/master/doc/configs.md#denols). +Install [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig/) and enable +the +[Deno configuration](https://github.com/neovim/nvim-lspconfig/blob/master/doc/configs.md#denols). -Note that if you also have `ts_ls` as an LSP client, you may run into issues -where both `ts_ls` and `denols` are attached to your current buffer. To resolve -this, make sure to set some unique `root_dir` for both `ts_ls` and `denols`. You -may also need to set `single_file_support` to `false` for `ts_ls` to prevent it -from running in `single file mode`. Here is an example of such a configuration: +If you also use `ts_ls`, set separate `root_markers` to avoid conflicts: ```lua vim.lsp.config('denols', { @@ -125,14 +94,10 @@ vim.lsp.config('ts_ls', { }) ``` -For Deno, the example above assumes a `deno.json` or `deno.jsonc` file exists at -the root of the project. - -##### Kickstart.nvim and Mason LSP +#### Kickstart.nvim and Mason LSP If you are using [kickstart.nvim](https://github.com/nvim-lua/kickstart.nvim) -add the above configuration like this inside the servers table in your -configuration `init.lua`. +add the configuration inside the servers table in your `init.lua`: ```lua local servers = { @@ -150,42 +115,26 @@ local servers = { } ``` -#### coc.nvim - -Once you have -[coc.nvim](https://github.com/neoclide/coc.nvim/wiki/Install-coc.nvim) -installed, you need to install the required -[coc-deno](https://github.com/fannheyward/coc-deno) via `:CocInstall coc-deno`. +### coc.nvim -Once the plugin is installed, and you want to enable Deno for a workspace, run -the command `:CocCommand deno.initializeWorkspace` and you should be able to -utilize commands like `gd` (goto definition) and `gr` (go/find references). +Install [coc.nvim](https://github.com/neoclide/coc.nvim/wiki/Install-coc.nvim), +then run `:CocInstall coc-deno` and `:CocCommand deno.initializeWorkspace`. -#### ALE +### ALE -ALE supports Deno via the Deno language server out of the box and in many uses -cases doesn't require additional configuration. Once you have -[ALE installed](https://github.com/dense-analysis/ale#installation) you can -perform the command -[`:help ale-typescript-deno`](https://github.com/dense-analysis/ale/blob/master/doc/ale-typescript.txt) -to get information on the configuration options available. +[ALE](https://github.com/dense-analysis/ale) supports Deno out of the box. Run +`:help ale-typescript-deno` for configuration options. -For more information on how to setup ALE (like key bindings) refer to the -[official documentation](https://github.com/dense-analysis/ale#usage). +### Vim-EasyComplete -#### Vim-EasyComplete +Install +[vim-easycomplete](https://github.com/jayli/vim-easycomplete#installation), then +run `:InstallLspServer deno`. -Vim-EasyComplete supports Deno without any other configuration. Once you have -[vim-easycomplete installed](https://github.com/jayli/vim-easycomplete#installation), -you need install deno via `:InstallLspServer deno` if you haven't installed -deno. You can get more information from -[official documentation](https://github.com/jayli/vim-easycomplete). +### Vim-Lsp -#### Vim-Lsp - -After installing Vim-Lsp through -[vim-plug](https://github.com/prabirshrestha/vim-lsp?tab=readme-ov-file#installing) -or vim packages. Add this code to your `.vimrc` configuration: +After installing [vim-lsp](https://github.com/prabirshrestha/vim-lsp), add to +your `.vimrc`: ```vim if executable('deno') @@ -204,32 +153,28 @@ if executable('deno') endif ``` -You will have two ways to enable the LSP Server. One is to have a `deno.json` or -`deno.jsonc` in your current working directory, or force it with -`DENO_ENABLE=1`. Also if you want to highlight syntax in the intellisense -tooltip, you can add this code to your `.vimrc` configuration too: +You can enable the LSP by having a `deno.json`/`deno.jsonc` in your working +directory, or by setting `DENO_ENABLE=1`. For syntax highlighting in tooltips, +add: ```vim let g:markdown_fenced_languages = ["ts=typescript"] ``` -### Emacs +
-#### lsp-mode +
+Emacs -Emacs supports Deno via the Deno language server using -[lsp-mode](https://emacs-lsp.github.io/lsp-mode/). Once -[lsp-mode is installed](https://emacs-lsp.github.io/lsp-mode/page/installation/) -it should support Deno, which can be -[configured](https://emacs-lsp.github.io/lsp-mode/page/lsp-deno/) to support -various settings. +### lsp-mode -#### eglot +Install [lsp-mode](https://emacs-lsp.github.io/lsp-mode/page/installation/) β€” +it supports Deno out of the box. +[Configuration options](https://emacs-lsp.github.io/lsp-mode/page/lsp-deno/). -You can also use built-in Deno language server by using -[`eglot`](https://github.com/joaotavora/eglot). +### eglot -An example configuration for Deno via eglot: +Use the built-in [`eglot`](https://github.com/joaotavora/eglot): ```elisp (add-to-list 'eglot-server-programs '((js-mode typescript-mode) . (eglot-deno "deno" "lsp"))) @@ -250,37 +195,17 @@ An example configuration for Deno via eglot: (:enabled t))))) ``` -This is the equivalent of having the following settings in a VSCode -`settings.json`: - -```jsonc -{ - "deno.enable": true, - "deno.unstable": true, - "typescript.inlayHints.variableTypes.enabled": true, - "typescript.inlayHints.parameterTypes.enabled": true -} -``` - -### Pulsar +
-The [Pulsar editor, formerly known as Atom](https://pulsar-edit.dev/) supports -integrating with the Deno language server via the -[atom-ide-deno](https://web.pulsar-edit.dev/packages/atom-ide-deno) package. -`atom-ide-deno` requires that the Deno CLI be installed and the -[atom-ide-base](https://web.pulsar-edit.dev/packages/atom-ide-base) package to -be installed as well. +
+Sublime Text, Zed, Helix, Kakoune, Pulsar, Nova ### Sublime Text -[Sublime Text](https://www.sublimetext.com/) supports connecting to the Deno -language server via the [LSP package](https://packagecontrol.io/packages/LSP). -You may also want to install the -[TypeScript package](https://packagecontrol.io/packages/TypeScript) to get full -syntax highlighting. - -Once you have the LSP package installed, you will want to add configuration to -your `.sublime-project` configuration like the below: +Install the [LSP package](https://packagecontrol.io/packages/LSP) and +optionally the +[TypeScript package](https://packagecontrol.io/packages/TypeScript). Add to your +`.sublime-project`: ```jsonc { @@ -289,9 +214,7 @@ your `.sublime-project` configuration like the below: "deno": { "command": ["deno", "lsp"], "initializationOptions": { - // "config": "", // Sets the path for the config file in your project "enable": true, - // "importMap": "", // Sets the path for the import-map in your project "lint": true, "unstable": false }, @@ -336,54 +259,15 @@ your `.sublime-project` configuration like the below: } ``` -### Nova - -The [Nova editor](https://nova.app) can integrate the Deno language server via -the -[Deno extension](https://extensions.panic.com/extensions/co.gwil/co.gwil.deno/). - -### GitHub Codespaces - -[GitHub Codespaces](https://github.com/features/codespaces) allows you to -develop fully online or remotely on your local machine without needing to -configure or install Deno. - -If a project is a Deno enabled project and contains the `.devcontainer` -configuration as part of the repository, opening the project in GitHub -Codespaces should just "work". If you are starting a new project, or you want to -add Deno support to an existing code space, it can be added by selecting the -`Codespaces: Add Development Container Configuration Files...` from the command -pallet and then selecting `Show All Definitions...` and then searching for the -`Deno` definition. - -Once selected, you will need to rebuild your container so that the Deno CLI is -added to the container. After the container is rebuilt, the code space will -support Deno. - -### Kakoune - -[Kakoune](https://kakoune.org/) supports connecting to the Deno language server -via the [kak-lsp](https://github.com/kak-lsp/kak-lsp) client. Once -[kak-lsp is installed](https://github.com/kak-lsp/kak-lsp#installation) an -example of configuring it up to connect to the Deno language server is by adding -the following to your `kak-lsp.toml`: +### Zed -```toml -[language.typescript] -filetypes = ["typescript", "javascript"] -roots = [".git"] -command = "deno" -args = ["lsp"] -[language.typescript.settings.deno] -enable = true -lint = true -``` +Install the +[Deno extension](https://zed.dev/extensions?query=deno&filter=language-servers) +from the extensions panel. ### Helix -[Helix](https://helix-editor.com) comes with built-in language server support. -Enabling connection to the Deno language server requires changes in the -`languages.toml` configuration file. +Add to your `languages.toml`: ```toml [[language]] @@ -406,60 +290,58 @@ args = ["lsp"] config.deno.enable = true ``` -### Zed - -The [Zed editor](https://zed.dev) can integrate the Deno language server via the -[Deno extension](https://zed.dev/extensions?query=deno&filter=language-servers). - -## Shell completions - -Built into the Deno CLI is support to generate shell completion information for -the CLI itself. By using `deno completions `, the Deno CLI will output to -stdout the completions. Current shells that are supported: +### Kakoune -- bash -- elvish -- fish -- powershell -- zsh +Install [kak-lsp](https://github.com/kak-lsp/kak-lsp) and add to your +`kak-lsp.toml`: -### bash example +```toml +[language.typescript] +filetypes = ["typescript", "javascript"] +roots = [".git"] +command = "deno" +args = ["lsp"] +[language.typescript.settings.deno] +enable = true +lint = true +``` -Output the completions and add them to the environment: +### Pulsar -```shell -> deno completions bash > /usr/local/etc/bash_completion.d/deno.bash -> source /usr/local/etc/bash_completion.d/deno.bash -``` +Install +[atom-ide-deno](https://web.pulsar-edit.dev/packages/atom-ide-deno) and +[atom-ide-base](https://web.pulsar-edit.dev/packages/atom-ide-base). -### PowerShell example +### Nova -Output the completions: +Install the +[Deno extension](https://extensions.panic.com/extensions/co.gwil/co.gwil.deno/). -```shell -> deno completions powershell >> $profile -> .$profile -``` +
-This will create a Powershell profile at -`$HOME\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1`, and it -will be run whenever you launch the PowerShell. +
+GitHub Codespaces -### zsh example +If the repository contains `.devcontainer` configuration, Deno will work +automatically. Otherwise, add the Deno dev container by selecting +**Codespaces: Add Development Container Configuration Files...** from the +command palette, then **Show All Definitions...**, and search for **Deno**. +Rebuild the container after selecting it. -You should have a directory where the completions can be saved: +
-```shell -> mkdir ~/.zsh -``` +## Shell completions -Then output the completions: +Generate shell completions for the Deno CLI: ```shell -> deno completions zsh > ~/.zsh/_deno +deno completions bash > /usr/local/etc/bash_completion.d/deno.bash +deno completions zsh > ~/.zsh/_deno +deno completions fish > ~/.config/fish/completions/deno.fish +deno completions powershell >> $profile ``` -And ensure the completions get loaded in your `~/.zshrc`: +For zsh, ensure the completions directory is in your `fpath` in `~/.zshrc`: ```shell fpath=(~/.zsh $fpath) @@ -467,47 +349,17 @@ autoload -Uz compinit compinit -u ``` -If after reloading your shell and completions are still not loading, you may -need to remove `~/.zcompdump/` to remove previously generated completions and -then `compinit` to generate them again. - -### zsh example with ohmyzsh and antigen - -[ohmyzsh](https://github.com/ohmyzsh/ohmyzsh) is a configuration framework for -zsh and can make it easier to manage your shell configuration. -[antigen](https://github.com/zsh-users/antigen) is a plugin manager for zsh. - -Create the directory to store the completions and output the completions: - -```shell -> mkdir ~/.oh-my-zsh/custom/plugins/deno -> deno completions zsh > ~/.oh-my-zsh/custom/plugins/deno/_deno -``` - -Then your `.zshrc` might look something like this: - -```shell -source /path-to-antigen/antigen.zsh +### Dynamic completions -# Load the oh-my-zsh's library. -antigen use oh-my-zsh - -antigen bundle deno -``` - -### fish example - -Output the completions to a `deno.fish` file into the completions directory in -the fish config folder: +Use the `--dynamic` flag to enable completions that are context-aware, such as +listing available tasks for `deno task`: ```shell -> deno completions fish > ~/.config/fish/completions/deno.fish +deno completions --dynamic bash > /usr/local/etc/bash_completion.d/deno.bash +deno completions --dynamic zsh > ~/.zsh/_deno +deno completions --dynamic fish > ~/.config/fish/completions/deno.fish +deno completions --dynamic powershell >> $profile ``` -## Other tools - -If you are writing or supporting a community integration using the Deno language -server, read more about -[integrating with the Deno LSP](/runtime/reference/lsp_integration/), but also -feel free to join our [Discord community](https://discord.gg/deno) in the -`#dev-lsp` channel. +With dynamic completions, typing `deno task ` will suggest the task names +from your project's `deno.json`. diff --git a/runtime/index.md b/runtime/index.md index 66708410d..52225bf2f 100644 --- a/runtime/index.md +++ b/runtime/index.md @@ -1,6 +1,6 @@ --- title: "Welcome to Deno" -description: "Learn the basics of Deno, a secure JavaScript, TypeScript, and WebAssembly runtime." +description: "Get started with Deno, the JavaScript and TypeScript toolkit with a built-in runtime, package manager, test runner, and compiler." pagination_next: /runtime/getting_started/first_project/ oldUrl: - /manual/ @@ -11,34 +11,13 @@ oldUrl: - / --- -[Deno](https://deno.com) -([/ˈdiːnoʊ/](https://ipa-reader.com/?text=%CB%88di%CB%90no%CA%8A), pronounced -`dee-no`) is an -[open source](https://github.com/denoland/deno/blob/main/LICENSE.md) JavaScript, -TypeScript, and WebAssembly runtime with secure defaults and a great developer -experience. It's built on [V8](https://v8.dev/), -[Rust](https://www.rust-lang.org/), and [Tokio](https://tokio.rs/). +[Deno](https://deno.com) is an +[open source](https://github.com/denoland/deno/blob/main/LICENSE.md) JavaScript +and TypeScript toolkit: a runtime, package manager, test runner, and compiler in +a single executable. It runs TypeScript natively, is secure by default, and works +with your existing npm packages. -## Why Deno? - -- Deno is - **[TypeScript-ready out of the box](/runtime/fundamentals/typescript/).** Zero - config or additional steps necessary. -- Deno is **[secure by default](/runtime/fundamentals/security/).** Where other - runtimes give full access every script they run, Deno allows you to enforce - granular permissions. -- Deno has a **robust built-in toolchain.** Unlike Node or browser JavaScript, - Deno includes a [standard library](/runtime/reference/std/), along with a - first-party [linter/formatter](/runtime/fundamentals/linting_and_formatting/), - [test runner](/runtime/fundamentals/testing/), and more. -- Deno is **fully compatible with [Node and npm](/runtime/fundamentals/node/).** -- Deno is **fast and reliable**. -- **[Deno is open-source](https://github.com/denoland/deno).** - -## Quick install - -Install the Deno runtime on your system using one of the terminal commands -below: +## Install @@ -50,8 +29,6 @@ curl -fsSL https://deno.land/install.sh | sh -In Windows PowerShell: - ```powershell irm https://deno.land/install.ps1 | iex ``` @@ -66,20 +43,68 @@ curl -fsSL https://deno.land/install.sh | sh -[Additional installation options can be found here](/runtime/getting_started/installation/). -After installation, you should have the `deno` executable available on your -system path. You can verify the installation by running: +[More installation options](/runtime/getting_started/installation/) | +Verify with `deno --version` + +## Try it + +An HTTP server in Deno: + +```ts title="server.ts" +Deno.serve((req) => { + const url = new URL(req.url); + + if (url.pathname === "/api") { + return Response.json({ message: "Hello, world!" }); + } + + return new Response("Welcome to Deno!"); +}); +``` ```sh -deno --version +$ deno run --allow-net server.ts +Listening on http://0.0.0.0:8000/ ``` -## First steps +No `package.json`, no build step, no `node_modules`. Just a `.ts` file and +`deno run`. -Deno can run JavaScript and [TypeScript](https://www.typescriptlang.org/) with -no additional tools or configuration required, all in a secure, -batteries-included runtime. +## What's included + +```sh +deno run server.ts # Run TypeScript and JavaScript +deno add npm:zod # Install npm and JSR packages +deno test # Run tests +deno fmt # Format code +deno lint # Lint code +deno check # Type-check without running +deno compile server.ts # Compile to a standalone binary +deno serve server.ts # Production-ready HTTP server +``` + +## Why Deno? -- [Making a Deno project](/runtime/getting_started/first_project/) -- [Setting up your environment](/runtime/getting_started/setup_your_environment/) -- [Using the CLI](/runtime/getting_started/command_line_interface) +- **TypeScript without config** β€” run `.ts` files directly, no `tsconfig.json` + or build step required. + [Learn more](/runtime/fundamentals/typescript/). +- **Secure by default** β€” no file, network, or environment access unless you + explicitly allow it. + [Learn more](/runtime/fundamentals/security/). +- **npm compatible** β€” import from npm with `npm:` specifiers, use Node built-in + APIs, and run in existing Node projects. + [Learn more](/runtime/fundamentals/node/). +- **Batteries included** β€” formatter, linter, test runner, LSP, and a + [standard library](/runtime/reference/std/) with no external dependencies. +- **Web standard APIs** β€” built on `fetch`, `Request`, `Response`, Web Streams, + `URLPattern`, and other platform APIs. + +## Next steps + +- [Create your first project](/runtime/getting_started/first_project/) β€” build + an HTTP server, add a dependency, write a test +- [Set up your editor](/runtime/getting_started/setup_your_environment/) β€” + VS Code, JetBrains, and other IDE support +- [Explore the CLI](/runtime/getting_started/command_line_interface/) β€” commands + and flags overview +- [Browse examples](/examples/) β€” ready-to-run code for common tasks