diff --git a/deploy/index.md b/deploy/index.md index 0f5cbc0a..02f1faf7 100644 --- a/deploy/index.md +++ b/deploy/index.md @@ -23,9 +23,9 @@ Click on the **+New Project** button There are three ways to deploy a new project in Deno Deploy: -- [Deploy with Github integration](./guide/ci_github) -- [Deploy with `deployctl`](./guide/deployctl) -- [Deploy with Deno Deploy Playground](./guide/playgrounds) +- [Deploy with Github integration](./manual/ci_github) +- [Deploy with `deployctl`](./manual/deployctl) +- [Deploy with Deno Deploy Playground](./manual/playgrounds) Select one of these methods, depending on the kind of project you have. @@ -34,15 +34,15 @@ Select one of these methods, depending on the kind of project you have. We generally recommend deploying with the Github integration because it is the fastest. If you need to run a CI build process first (for example generating static assets), we recommend deploying with the Github integration, and -selecting [Github Action](./guide/ci_github#github-action) +selecting [Github Action](./manual/ci_github#github-action) ## **Step 3:** Adjust project settings if necessary Once the project has been created, you can adjust a number of project settings on the **Settings** tab. For more details, follow the links below. -- [Custom domain](./guide/custom-domains) -- [Environment variables](./guide/environment-variables) +- [Custom domain](./manual/custom-domains) +- [Environment variables](./manual/environment-variables) ## **Step 4:** Find project URL @@ -51,4 +51,3 @@ The production URL is the URL that your production deployment can be reached at. The project name will determine a project's production URL. It has the form `$PROJECT_ID.deno.dev` (e.g. https://dead-clam-55.deno.dev). - diff --git a/deploy/guide/ci_github.md b/deploy/manual/ci_github.md similarity index 100% rename from deploy/guide/ci_github.md rename to deploy/manual/ci_github.md diff --git a/deploy/guide/compression.md b/deploy/manual/compression.md similarity index 100% rename from deploy/guide/compression.md rename to deploy/manual/compression.md diff --git a/deploy/guide/custom-domains.md b/deploy/manual/custom-domains.md similarity index 100% rename from deploy/guide/custom-domains.md rename to deploy/manual/custom-domains.md diff --git a/deploy/guide/deployctl.md b/deploy/manual/deployctl.md similarity index 100% rename from deploy/guide/deployctl.md rename to deploy/manual/deployctl.md diff --git a/deploy/guide/deployments.md b/deploy/manual/deployments.md similarity index 100% rename from deploy/guide/deployments.md rename to deploy/manual/deployments.md diff --git a/deploy/guide/dynamodb.md b/deploy/manual/dynamodb.md similarity index 100% rename from deploy/guide/dynamodb.md rename to deploy/manual/dynamodb.md diff --git a/deploy/guide/environment-variables.md b/deploy/manual/environment-variables.md similarity index 100% rename from deploy/guide/environment-variables.md rename to deploy/manual/environment-variables.md diff --git a/deploy/guide/fair-use-policy.md b/deploy/manual/fair-use-policy.md similarity index 100% rename from deploy/guide/fair-use-policy.md rename to deploy/manual/fair-use-policy.md diff --git a/deploy/guide/faunadb.md b/deploy/manual/faunadb.md similarity index 100% rename from deploy/guide/faunadb.md rename to deploy/manual/faunadb.md diff --git a/deploy/guide/firebase.md b/deploy/manual/firebase.md similarity index 100% rename from deploy/guide/firebase.md rename to deploy/manual/firebase.md diff --git a/deploy/guide/how-to-deploy.md b/deploy/manual/how-to-deploy.md similarity index 100% rename from deploy/guide/how-to-deploy.md rename to deploy/manual/how-to-deploy.md diff --git a/deploy/guide/index.md b/deploy/manual/index.md similarity index 98% rename from deploy/guide/index.md rename to deploy/manual/index.md index 66f376ca..b02c7de6 100644 --- a/deploy/guide/index.md +++ b/deploy/manual/index.md @@ -2,7 +2,7 @@ displayed_sidebar: deployGuideHome sidebar_position: 1 sidebar_label: Overview -pagination_next: guide/how-to-deploy +pagination_next: manual/how-to-deploy --- # About Deno Deploy diff --git a/deploy/guide/kv.md b/deploy/manual/kv.md similarity index 98% rename from deploy/guide/kv.md rename to deploy/manual/kv.md index 44b19fd4..f593e319 100644 --- a/deploy/guide/kv.md +++ b/deploy/manual/kv.md @@ -10,7 +10,7 @@ Additionally, Deno KV is available within Deno itself, utilizing SQLite as its backend. This feature has been accessible since Deno v1.32 with the `--unstable` flag. -[Discover how to effectively use the Deno KV database by referring to the Deno Runtime user guide.](/runtime/guide/runtime/kv) +[Discover how to effectively use the Deno KV database by referring to the Deno Runtime user guide.](/runtime/manual/runtime/kv) ## Getting started diff --git a/deploy/guide/logs.md b/deploy/manual/logs.md similarity index 100% rename from deploy/guide/logs.md rename to deploy/manual/logs.md diff --git a/deploy/guide/middleware.md b/deploy/manual/middleware.md similarity index 100% rename from deploy/guide/middleware.md rename to deploy/manual/middleware.md diff --git a/deploy/guide/organizations.md b/deploy/manual/organizations.md similarity index 100% rename from deploy/guide/organizations.md rename to deploy/manual/organizations.md diff --git a/deploy/guide/playgrounds.md b/deploy/manual/playgrounds.md similarity index 100% rename from deploy/guide/playgrounds.md rename to deploy/manual/playgrounds.md diff --git a/deploy/guide/postgres.md b/deploy/manual/postgres.md similarity index 100% rename from deploy/guide/postgres.md rename to deploy/manual/postgres.md diff --git a/deploy/guide/pricing-and-limits.md b/deploy/manual/pricing-and-limits.md similarity index 100% rename from deploy/guide/pricing-and-limits.md rename to deploy/manual/pricing-and-limits.md diff --git a/deploy/guide/privacy-policy.md b/deploy/manual/privacy-policy.md similarity index 100% rename from deploy/guide/privacy-policy.md rename to deploy/manual/privacy-policy.md diff --git a/deploy/guide/regions.md b/deploy/manual/regions.md similarity index 100% rename from deploy/guide/regions.md rename to deploy/manual/regions.md diff --git a/deploy/guide/running-scripts-locally.md b/deploy/manual/running-scripts-locally.md similarity index 100% rename from deploy/guide/running-scripts-locally.md rename to deploy/manual/running-scripts-locally.md diff --git a/deploy/guide/security.md b/deploy/manual/security.md similarity index 100% rename from deploy/guide/security.md rename to deploy/manual/security.md diff --git a/deploy/guide/use-cases.md b/deploy/manual/use-cases.md similarity index 98% rename from deploy/guide/use-cases.md rename to deploy/manual/use-cases.md index f29f89fb..a6aec124 100644 --- a/deploy/guide/use-cases.md +++ b/deploy/manual/use-cases.md @@ -1,3 +1,5 @@ +# Deno Deploy Use Cases + Some popular use-cases for Deno currently are: - [Middleware](#middleware) diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 4594684e..00000000 --- a/docs/index.md +++ /dev/null @@ -1,3 +0,0 @@ -# Deno Docs - -[Please return home](/), nothing to see here! diff --git a/docusaurus.config.js b/docusaurus.config.js index 2d2a31a9..54e81f11 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -39,10 +39,10 @@ const config = { /** @type {import('@docusaurus/preset-classic').Options} */ ({ docs: { - sidebarPath: require.resolve("./sidebars.js"), - // Please change this to your repo. - // Remove this to remove the "edit this page" links. - editUrl: "https://github.com/denoland/deno-docs/", + id: "runtime", + path: "runtime", + routeBasePath: "runtime", + sidebarPath: require.resolve("./sidebars/runtime.js"), }, /* blog: { @@ -73,24 +73,17 @@ const config = { ], plugins: [ - [ - "@docusaurus/plugin-content-docs", - { - id: "runtime", - path: "runtime", - routeBasePath: "runtime", - sidebarPath: require.resolve("./sidebars/runtime.js"), - }, - ], + /* [ "@docusaurus/plugin-content-docs", { id: "stdlib", path: "stdlib", routeBasePath: "stdlib", - sidebarPath: require.resolve("./sidebars.js"), + sidebarPath: require.resolve("./sidebars/runtime.js"), }, ], + */ [ "@docusaurus/plugin-content-docs", { @@ -255,7 +248,7 @@ const config = { }, { label: "Privacy Policy", - href: "/deploy/guide/privacy-policy", + href: "/deploy/manual/privacy-policy", }, ], }, diff --git a/runtime/index.md b/runtime/index.md index b37431b7..a3de39e7 100644 --- a/runtime/index.md +++ b/runtime/index.md @@ -45,7 +45,7 @@ curl -fsSL https://deno.land/x/install/install.sh | sh -[Additional installation options can be found here](./guide/getting_started/installation.md). +[Additional installation options can be found here](./manual/getting_started/installation.md). After installation, you should have the `deno` executable available on your system path. You can confirm this is the case by running this command in your terminal: @@ -66,14 +66,16 @@ interface Person { lastName: string } -function sayHello(p: Person) { - console.log(`Hello, ${p.firstName}!`); +function sayHello(p: Person): string { + return `Hello, ${p.firstName}!`; } -sayHello({ +const ada: Person = { firstName: "Ada", lastName: "Lovelace" -}); +}; + +console.log(sayHello(ada)); ``` This program declares an @@ -83,45 +85,342 @@ this data type. You can execute the code in this example using the `deno run` command. ``` -deno run hello.ts +deno run -A hello.ts ``` +You can +[learn more about using TypeScript in Deno here](./manual/advanced/typescript/index.md). + ## Built-in web APIs and the Deno namespace -**TODO:** introduce the idea that, like the browser, many APIs are built in and -globally available. Also introduce the `Deno` namespace, and when you'd use it. +Deno aims to provide a browser-like programming environment, +[implementing web standard APIs](./manual/runtime/web_platform_apis.md) that +exist in front-end JavaScript. For example, the +[`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) API is +available in the global scope, just as in the browser. To see this in action, +replace the contents of `hello.ts` with the following code. + +```ts +const site = await fetch("https://www.deno.com"); +console.log(await site.text()); +``` + +And then run it with: + +``` +deno run -A hello.ts +``` + +For APIs that don't exist as a web standard (like accessing variables from the +system environment, or manipulating the file system), those APIs are exposed in +the [`Deno` namespace](./manual/runtime/builtin_apis.md). Replace the contents +of `hello.ts` with the following code, which will start +[an HTTP server](https://deno.land/api?s=Deno.serve) on +[localhost:8000](http://localhost:8000). + +```ts +Deno.serve((_request: Request) => { + return new Response("Hello, world!"); +}); +``` + +Run the script above with: + +``` +deno run -A hello.ts +``` + +Learn more about the [web-standard APIs](./manual/runtime/web_platform_apis.md) +built in to Deno and the +[`Deno` namespace APIs](./manual/runtime/builtin_apis.md). + +## Runtime security + +A major feature of Deno is +[runtime security by default](./manual/basics/permissions.md), meaning that you +as the developer must explicitly allow your code to access potentially sensitive +APIs like file system access, network connectivity, and access to environment +variables. + +So far, we've been running all of our scripts with the `-A` flag, which grants +all runtime feature access to our scripts. This is the most permissive mode to +run a Deno program, but usually you'll want to grant your code only the +permissions it needs to run. + +To see this in action, let's replace the contents of `hello.ts` again with the +`fetch` example from earlier. + +```ts +const site = await fetch("https://www.deno.com"); +console.log(await site.text()); +``` + +Run this program **without** the `-A` flag - what happens then? -## Executing code with permissions +```ts +deno run hello.ts +``` -**TODO:** introduce the concept of permissions with an `--allow-net` example, -using `fetch`. +Without any permission flags passed in, you'll see security prompts that look +something like this: + +``` +kevin@kevin-deno scratchpad % deno run index.ts +✅ Granted net access to "www.deno.com". +┌ ⚠️ Deno requests net access to "deno.com". +├ Requested by `fetch()` API. +├ Run again with --allow-net to bypass this prompt. +└ Allow? [y/n/A] (y = yes, allow; n = no, deny; A = allow all net permissions) > +``` + +For simplicity, we will sometimes show examples that use `deno run -A ...`, but +whenever possible (and in your production or CI environments), we'd encourage +you to take advantage of Deno's full suite of +[configurable runtime security options](./manual/basics/permissions.md). ## Importing JavaScript modules -**TODO:** talk about how Deno embraces -[modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) -and give local and remote examples (using standard library). +Most of the time, you will want to break up your program into multiple files. +Again favoring web standards and a browser-like programming model, Deno supports +this through +[ECMAScript modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules). +Consider the earlier TypeScript example we showed you: + +```ts title="hello.ts" +interface Person { + firstName: string, + lastName: string +} + +function sayHello(p: Person): string { + return `Hello, ${p.firstName}!`; +} + +const ada: Person = { + firstName: "Ada", + lastName: "Lovelace" +}; + +console.log(sayHello(ada)); +``` + +You might want to break this program up such that the `Person` interface and the +`sayHello` function are in a separate module. To do this, create a new file in +the same directory called `person.ts` and include the following code: + +```ts title="person.ts" +export default interface Person { + firstName: string, + lastName: string +} + +export function sayHello(p: Person): string { + return `Hello, ${p.firstName}!`; +} +``` + +This module creates a +[named export](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#exporting_module_features) +for the `sayHello` function, and a +[default export](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#default_exports_versus_named_exports) +for the `Person` interface. + +Back in `hello.ts`, you would consume this module using the `import` keyword. + +```ts title="hello.ts" +import Person, { sayHello } from "./person.ts"; + +const ada: Person = { + lastName: "Lovelace", + firstName: "Ada", +}; + +console.log(sayHello(ada)); +``` + +:::info File extensions required in imports + +Note that **file extensions are required** when importing modules - import logic +in Deno works as it does in the browser, where you would include the full file +name of your imports. + +::: + +[You can learn more about the module system in Deno here](./manual/basics/modules/index.md). + +## Remote modules and the Deno standard library + +Deno supports loading and executing code from URLs, much as you would using a +`