License

LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2023 the Deno Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

runtime/manual/basics/modules/index.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 1
----
-
 # ECMAScript Modules in Deno
 
 ## Concepts

runtime/manual/node/compatibility.mdx

@@ -7,11 +7,21 @@ which modules you need by
 
 ## Built-in module support
 
-✅ = Full support   ℹ️ = Partial support   ❌ = Stubs only
+<div style={{
+  display: "flex",
+  flexDirection: "row",
+  gap: "10px",
+  flexWrap: "wrap",
+  marginBottom: "10px"
+}}>
+  <div>✅ = Full support</div>
+  <div>ℹ️ = Partial support</div>
+  <div>❌ = Stubs only</div>
+</div>
 
 <details>
   <summary>
-    <code>node:assert</code>, <code>node:assert/strict</code>
+    <code>node:assert</code>
     <div style={{ float: "right" }}>
       <span>✅</span>
     </div>
@@ -201,7 +211,7 @@ which modules you need by
 
 <details>
   <summary>
-    <code>node:fs</code>, <code>node:fs/promises</code>
+    <code>node:fs</code>
     <div style={{ float: "right" }}>
       <span>ℹ️</span>
     </div>
@@ -450,8 +460,7 @@ which modules you need by
 
 <details>
   <summary>
-    <code>node:stream</code>, <code>node:stream/consumers</code>,&nbsp;
-    <code>node:stream/promises</code>, <code>node:stream/web</code>
+    <code>node:stream</code>
     <div style={{ float: "right" }}>
       <span>✅</span>
     </div>
@@ -512,7 +521,7 @@ which modules you need by
 
 <details>
   <summary>
-    <code>node:timers</code>, <code>node:timers/promises</code>
+    <code>node:timers</code>
     <div style={{ float: "right" }}>
       <span>✅</span>
     </div>

runtime/manual/node/migrate.md

@@ -5,19 +5,14 @@ differences to take into account between the Node and Deno runtimes. This guide
 will attempt to call out several of those differences, and describe how you can
 begin to migrate your Node.js project to work on Deno.
 
-> Node.js compatibility is an ongoing project in Deno - you may encounter some
-> modules or packages on npm that do not work as you expect. If you do run into
-> a problem with Node.js compatibility, please let us know by
-> [opening an issue on GitHub](https://github.com/denoland/deno/issues).
+:::info About Node.js Compatibility
 
-**On this page:**
+Node.js compatibility is an ongoing project in Deno - you may encounter some
+modules or packages on npm that do not work as you expect. If you do run into a
+problem with Node.js compatibility, please let us know by
+[opening an issue on GitHub](https://github.com/denoland/deno/issues).
 
-- [Module imports and exports](#module-imports-and-exports)
-- [Node.js built-ins](#nodejs-built-ins)
-- [Runtime permission system](#runtime-permissions-in-deno)
-- [npm scripts](#running-npm-scripts-in-deno)
-- [Using and managing npm dependencies](#using-and-managing-npm-dependencies)
-- [Node.js global objects](#nodejs-global-objects)
+:::
 
 ## Module imports and exports
 
@@ -31,16 +26,12 @@ be changed as well.
 Consider the following two files in a Node.js program, located in the same
 directory:
 
-**`index.js`**
-
-```js
+```js title="index.js"
 const addNumbers = require("./add_numbers");
 console.log(addNumbers(2, 2));
 ```
 
-**`add_numbers.js`**
-
-```js
+```js title="add_numbers.js"
 module.exports = function addNumbers(num1, num2) {
   return num1 + num2;
 };
@@ -56,7 +47,7 @@ module.
 
 Replace `require` statements with an `import`, like so:
 
-```
+```js
 import addNumbers from "./add_numbers.js";
 ```
 
@@ -70,7 +61,7 @@ of files named `index.js`.
 In the `add_numbers.js` file that exports the function, we would use a default
 export from ES6 modules rather than the `module.exports` provided by CommonJS.
 
-```js
+```js title="add_numbers.js"
 export default function addNumbers(num1, num2) {
   return num1 + num2;
 }
@@ -86,19 +77,21 @@ In Node.js 20 and earlier, built-in modules in the Node.js standard library
 could be imported with "bare specifiers". Consider the Node program below with a
 `.mjs` extension:
 
-**`index.mjs`**
-
-```
+```js title="index.mjs"
 import * as os from "os";
 console.log(os.cpus());
 ```
 
 The [`os` module](https://nodejs.org/api/os.html#oscpus) is built in to the
 Node.js runtime, and can be imported using a bare specifier as above.
 
-> **NOTE:** The `.mjs` file extension is supported but not required in Deno.
-> Because Node doesn't support ESM by default, it requires you to name any files
-> that use ESM with a `.mjs` file extension.
+:::info .mjs extensions not required in Deno
+
+The `.mjs` file extension is supported but not required in Deno. Because Node
+doesn't support ESM by default, it requires you to name any files that use ESM
+with a `.mjs` file extension.
+
+:::
 
 Deno provides a compatibility layer that allows the use of Node.js built-in APIs
 within Deno programs. However, in order to use them, you will need to add the
@@ -133,7 +126,7 @@ will likely prompt you for access to the permissions it needs to execute your
 code. Consider the following simple [express](https://expressjs.com/) server:
 
 ```js
-import express from "npm:express";
+import express from "npm:express@4";
 
 const app = express();
 
@@ -152,7 +145,7 @@ show you what runtime permission flags need to be passed in to grant the access
 you need. Running the code above with the necessary permissions provided would
 look like this:
 
-```plain
+```shell
 deno run --allow-net --allow-read --allow-env server.js
 ```
 
@@ -180,7 +173,7 @@ run your programs with all runtime permissions enabled. This would be the
 default behavior of Node, which lacks a permission system. To run a program with
 all permissions enabled, you can do so with:
 
-```plain
+```shell
 deno run -A server.js
 ```
 
@@ -197,19 +190,15 @@ One of the ways [Deno supports existing `package.json` files](./package_json.md)
 is by executing any scripts configured there with `deno task`. Consider the
 following Node.js project with a package.json and a script configured within it.
 
-**`bin/my_task.mjs`**
-
-```js
+```js title="bin/my_task.mjs"
 console.log("running my task...");
 ```
 
-**`package.json`**
-
-```json
+```json title="package.json"
 {
   "name": "test",
   "scripts": {
-    "start": "node index.mjs"
+    "start": "node bin/my_task.mjs"
   }
 }
 ```
@@ -232,7 +221,7 @@ When importing npm packages, you would use the `npm:` specifier, much like you
 would the `node:` specifier for any built-in Node modules.
 
 ```js
-import express from "npm:express";
+import express from "npm:express@4";
 
 const app = express();
 

runtime/manual/node/node_specifiers.md

@@ -6,7 +6,7 @@ Deno supports using Node.js built-in modules such as
 [process](https://nodejs.org/api/process.html#process), and many more via
 `node:` specifiers.
 
-```ts, ignore
+```ts
 import { readFileSync } from "node:fs";
 
 console.log(readFileSync("deno.json", { encoding: "utf8" }));

runtime/manual/node/package_json.md

@@ -5,9 +5,7 @@ current or ancestor directories. This is similar to how Node.js resolves
 dependencies. We recommend using import maps with `deno.json` which is explained
 [here](../basics/import_maps.md).
 
-**package.json**
-
-```json
+```json title="package.json"
 {
   "name": "@deno/my-example-project",
   "description": "An example app created with Deno",
@@ -21,24 +19,22 @@ dependencies. We recommend using import maps with `deno.json` which is explained
 }
 ```
 
-**main.ts**
-
-```ts, ignore
+```ts title="main.ts"
 import chalk from "chalk";
 
 console.log(chalk.green("Hello from Deno!"));
 ```
 
 Then we can run this script:
 
-```shell, ignore
+```shell
 > deno run --allow-env --allow-sys main.ts
 Hello from Deno!
 ```
 
 Or also execute package.json scripts via `deno task`:
 
-```shell, ignore
+```shell
 > deno task dev
 Hello from Deno!
 ```

runtime/manual/runtime/http_server_apis.md

@@ -1,13 +1,12 @@
 # HTTP Server APIs
 
-Deno currently has three HTTP Server APIs:
+Deno currently has two HTTP Server APIs:
 
 - [`Deno.serve`](https://deno.land/api?s=Deno.serve): native, _higher-level_,
   supports HTTP/1.1 and HTTP2, this is the preferred API to write HTTP servers
   in Deno.
 - [`Deno.serveHttp`](https://deno.land/api?s=Deno.serveHttp): native,
   _low-level_, supports HTTP/1.1 and HTTP2.
-
 - [A "Hello World" server](#a-hello-world-server)
 - [Inspecting the incoming request](#inspecting-the-incoming-request)
 - [Responding with a response](#responding-with-a-response)

runtime/manual/runtime/permission_apis.md

@@ -36,8 +36,8 @@ const desc5 = { name: "hrtime" } as const;
 ```
 
 > ⚠️ See
-> [`PermissionDescriptor`](https://www.deno.land/api?s=Deno.PermissionDescriptor)
-> in API reference for more details.
+> [`PermissionDescriptor`](https://deno.land/api?s=Deno.PermissionDescriptor) in
+> API reference for more details.
 
 > ⚠️ In 1.30 and onwards, synchronous API counterparts (ex.
 > `Deno.permissions.querySync`) exist for all the APIs described below.

runtime/manual/runtime/web_platform_apis.md

@@ -1,12 +1,13 @@
 # Using Web Platform APIs
 
-Deno aims to use web platform APIs (like `fetch`) instead of inventing a new
-proprietary API where it makes sense. These APIs generally follow the
-specifications and should match the implementation in Chrome and Firefox. In
-some cases it makes sense to deviate from the spec slightly, because of the
-different security model Deno has.
+One way Deno simplifies web and cloud development is by using Web Platform APIs
+(like `fetch`) over proprietary APIs. This means if you've ever built for the
+browser, you're likely already familiar with Deno, and if you're learning Deno,
+you're also investing in your knowledge of the web.
 
-Here is a list of web platform APIs Deno implements:
+## Supported APIs
+
+Here's a partial list of supported web platform APIs in Deno:
 
 - [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob)
 - [BroadcastChannel](https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel)
@@ -33,7 +34,12 @@ Here is a list of web platform APIs Deno implements:
 - [Web Workers API](https://developer.mozilla.org/en-US/docs/Web/API/Worker)
 - [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
 
-You can find the Deno reference for these APIs [here](https://deno.land/api).
+You can find the Deno reference for these APIs [here](https://deno.land/api). To
+check if a Web Platform API is available in Deno, click on
+[the interface on MDN](https://developer.mozilla.org/en-US/docs/Web/API#interfaces)
+and refer to
+[its Browser Compatibility table](https://developer.mozilla.org/en-US/docs/Web/API/AbortController#browser_compatibility)
+(link as an example).
 
 ## `fetch` API