From 7ae4d898b9b44d013e8eb3e6f05475307c545870 Mon Sep 17 00:00:00 2001 From: Dario Piotrowicz Date: Sun, 14 Jan 2024 23:31:16 +0000 Subject: [PATCH 1/4] clarify how presets work --- docs/content/2.deploy/0.index.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/content/2.deploy/0.index.md b/docs/content/2.deploy/0.index.md index dab04b6b47..a7d21bc957 100644 --- a/docs/content/2.deploy/0.index.md +++ b/docs/content/2.deploy/0.index.md @@ -17,7 +17,7 @@ When running Nitro in development mode, Nitro will always use a special preset c ## Zero-Config Providers -When deploying to the production using CI/CD, Nitro tries to automatically detect the provider environment and set the right one without any additional configuration. Currently, providers below can be auto-detected with zero config. +When deploying to production using CI/CD, Nitro tries to automatically detect the provider environment and set the right one without any additional configuration required. Currently, the providers below can be auto-detected with zero config. - [aws amplify](/deploy/providers/aws-amplify) - [azure](/deploy/providers/azure) @@ -27,19 +27,25 @@ When deploying to the production using CI/CD, Nitro tries to automatically detec - [vercel](/deploy/providers/vercel) - [zeabur](/deploy/providers/zeabur) +::alert{type="info"} +**Note:** Even with these presets, if you need to build your application locally (for development or testing purposes) targeting the provider environment, you still need to tell Nitro what preset it needs to use (you can see below how). +:: + ## Changing the deployment preset -If you need to build Nitro against a specific provider, you can override it using an environment variable or `nitro.config.ts`. Using environment variable is recommended for deployments depending on CI/CD. +If you need to build Nitro against a specific provider, you can target it by defining an environment variable named `NITRO_PRESET` or `SERVER_PRESET`, or by updating your Nitro [configuration](/guide/configuration). + +Using the environment variable approach is recommended for deployments depending on CI/CD. -**Example:** Using `NITRO_PRESET` +**Example:** Defining a `NITRO_PRESET` environment variable ```bash NITRO_PRESET=aws_lambda nitro build ``` -**Example:** Using [nitro.config.ts](/guide/configuration) +**Example:** Updating the `nitro.config.ts` file ```ts export default defineNitroConfig({ - preset: 'node-server' + preset: 'aws_lambda' }) ``` From e7a51e1d3cfd0439c23edd015f6e976540aefbd0 Mon Sep 17 00:00:00 2001 From: Dario Piotrowicz Date: Sun, 14 Jan 2024 23:32:54 +0000 Subject: [PATCH 2/4] update the cloudflare deployment documentation as part of these changes: - make the `cloudflare_pages` preset the recommended one - make the worker presets deprecated - give more information regarding Bindings --- .../2.deploy/20.providers/cloudflare.md | 293 +++++++----------- 1 file changed, 117 insertions(+), 176 deletions(-) diff --git a/docs/content/2.deploy/20.providers/cloudflare.md b/docs/content/2.deploy/20.providers/cloudflare.md index 3355bb0bea..c2f1dbd331 100644 --- a/docs/content/2.deploy/20.providers/cloudflare.md +++ b/docs/content/2.deploy/20.providers/cloudflare.md @@ -2,158 +2,119 @@ Deploy Nitro apps to CloudFlare. -## Cloudflare Workers +## Cloudflare Pages -**Preset:** `cloudflare` ([switch to this preset](/deploy/#changing-the-deployment-preset)) +**Preset:** `cloudflare_pages` ([switch to this preset](/deploy/#changing-the-deployment-preset)) -::alert{type="info"} -**Note:** This preset uses [service-worker syntax](https://developers.cloudflare.com/workers/learning/service-worker/) for deployment. +::alert +**Note:** This is the recommended preset for Cloudflare deployments, please consider using the alternative ones only if you have special requirements or needs. :: -Create a `wrangler.toml` in your root directory: +::alert +**Zero Config Provider** +:br +Integration with this provider is possible with zero configuration. ([Learn More](/deploy/#zero-config-providers)) +:: -```ini -name = "playground" -main = "./.output/server/index.mjs" -workers_dev = true -compatibility_date = "2023-12-01" -# account_id = "<(optional) your Cloudflare account id, retrievable from the Cloudflare dashboard>" -# route = "<(optional) mainly useful when you want to setup custom domains>" +Nitro automatically generates a `_routes.json` file that controls which routes get served from files and which are served from the Worker script. The auto-generated routes file can be overridden with the config option `cloudflare.pages.routes` ([read more](https://developers.cloudflare.com/pages/platform/functions/routing/#functions-invocation-routes)). -rules = [ - { type = "ESModule", globs = ["**/*.js", "**/*.mjs"]}, -] +### Building your Application using the preset -[site] -bucket = ".output/public" -``` +The preset only applies for the application build process. -### Preview your app locally +If you use the [Cloudflare Pages GitHub/GitLab integration](https://developers.cloudflare.com/pages/get-started/#connect-your-git-provider-to-pages), and you don't need to preview your application locally, Nitro does not require any type of configuration. When you push to your repository, the Cloudflare Pages CI/CD process will automatically build your project and Nitro will detect the correct environment and build your application accordingly. -You can use [wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler), to preview your app locally: +If instead you want preview your application locally and/or manually deploy it, when building the application you will need to let Nitro know that the target environment is the Cloudflare Pages one, you can do that in two ways: +1. By defining either the `NITRO_PRESET` or the `SERVER_PRESET` environment variable set to `cloudflare-pages` when running the build process, like so: ```bash -NITRO_PRESET=cloudflare npm run build - -# If you have added a 'wrangler.toml' file like above in the root of your project: -npx wrangler dev +NITRO_PRESET=cloudflare-pages npm run build +``` -# If you don't have a 'wrangler.toml', directly use: -npx wrangler dev .output/server/index.mjs --site .output/public +1. Or by updating your Nitro [preset configuration](/config#preset): +```json5 +"preset": "cloudflare-pages", +``` +and then running the standard build command: +```bash +npm run build ``` -### Deploy from your local machine using wrangler +### Wrangler -Install [wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler) and login to your Cloudflare account: +To preview your application locally or manually deploy it you will need to use the [wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler) CLI tool, simply install it as a node dependency: ```bash npm i wrangler -wrangler login ``` -Generate website with the `cloudflare` preset: +### Preview your app locally + +After having built your application you can preview it locally with wrangler by running: ```bash -NITRO_PRESET=cloudflare npm run build +npx wrangler pages dev dist ``` -You can preview locally: +### Deploy your app locally -```bash -# If you have a 'wrangler.toml' like above: -npx wrangler dev +After having built your application you can manually deploy it with wrangler, in order to do so first make sure to be +logged into your Cloudflare account: -# If you don't have a 'wrangler.toml': -npx wrangler dev .output/server/index.mjs --site .output/public +```bash +npx wrangler login ``` -Publish: +Then you can deploy the application with: ```bash -npx wrangler deploy +npx wrangler pages deploy dist ``` -### Deploy within CI/CD using GitHub Actions - -Create a token according to [the wrangler action docs](https://github.com/marketplace/actions/deploy-to-cloudflare-workers-with-wrangler#authentication) and set `CLOUDFLARE_API_TOKEN` in your repository config on GitHub. - -Create `.github/workflows/cloudflare.yml`: +## Cloudflare Module Workers -```yaml -name: cloudflare +**Preset:** `cloudflare_module` ([switch to this preset](/deploy/#changing-the-deployment-preset)) -on: - push: - branches: - - main - pull_request: - branches: - - main +::alert{type="info"} +**Note:** This preset uses the [module worker syntax](https://developers.cloudflare.com/workers/learning/migrating-to-module-workers/) for deployment. +:: -jobs: - deploy: - runs-on: ubuntu-latest - name: Deploy - steps: - - name: Checkout - uses: actions/checkout@v3 +::alert{type="warning"} +**Note:** This preset is deprecated. +:: - - name: Setup Node.js - uses: actions/setup-node@v3 - with: - node-version: 20.x +When using Workers you will need a `wrangler.toml` file, in your root directory. - - name: Install npm dependencies - run: npm ci +The following shows a typical `wrangler.toml` file for a Nitro application: - - name: Build - run: npm run build - env: - NITRO_PRESET: cloudflare +```ini +name = "playground" +main = "./.output/server/index.mjs" +workers_dev = true +compatibility_date = "2023-12-01" +# account_id = "<(optional) your Cloudflare account id, retrievable from the Cloudflare dashboard>" +# route = "<(optional) mainly useful when you want to setup custom domains>" - - name: Deploy - uses: cloudflare/wrangler-action@v3 - with: - apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} +rules = [ + { type = "ESModule", globs = ["**/*.js", "**/*.mjs"]}, +] +[site] +bucket = ".output/public" ``` -## Cloudflare Pages - -**Preset:** `cloudflare_pages` ([switch to this preset](/deploy/#changing-the-deployment-preset)) - -::alert{type="warning"} -**Note:** This is an experimental preset. -:: - -::alert -**Zero Config Provider** -:br -Integration with this provider is possible with zero configuration. ([Learn More](/deploy/#zero-config-providers)) -:: - -Nitro automatically generates a `_routes.json` file that controls which routes get served from files and which are served from the Worker script. The auto-generated routes file can be overridden with the config option `cloudflare.pages.routes` ([read more](https://developers.cloudflare.com/pages/platform/functions/routing/#functions-invocation-routes)). - ### Preview your app locally You can use [wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler), to preview your app locally: ```bash -NITRO_PRESET=cloudflare-pages npm run build - -npx wrangler pages dev dist -``` - -### Git integration - -If you use the GitHub/GitLab [integration](https://developers.cloudflare.com/pages/get-started/#connect-your-git-provider-to-pages) with Pages, Nitro does not require any configuration. When you push to the repository, Pages will automatically build your project, and Nitro will detect the environment. - -### Direct Upload +NITRO_PRESET=cloudflare npm run build -Alternatively, you can use [wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler) to upload your project to Cloudflare. In this case, you will have to set the preset manually: +# If you have added a 'wrangler.toml' file like above in the root of your project: +npx wrangler dev -```bash -NITRO_PRESET=cloudflare-pages npm run build +# If you don't have a 'wrangler.toml', directly use: +npx wrangler dev .output/server/index.mjs --site .output/public ``` ### Deploy from your local machine using wrangler @@ -162,86 +123,68 @@ Install [wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/ ```bash npm i wrangler -npx wrangler login +wrangler login ``` -Create project: +Generate your app using the `cloudflare` preset: ```bash -npx wrangler pages project create +NITRO_PRESET=cloudflare_module npm run build ``` -Deploy: +You can then preview it locally: ```bash -npx wrangler pages deploy dist +# If you have a 'wrangler.toml' like above: +npx wrangler dev + +# If you don't have a 'wrangler.toml': +npx wrangler dev .output/server/index.mjs --site .output/public ``` -## Cloudflare Module Workers +and publish it: -**Preset:** `cloudflare_module` ([switch to this preset](/deploy/#changing-the-deployment-preset)) +```bash +npx wrangler deploy +``` -::alert{type="warning"} -**Note:** This is an experimental preset. -:: +## Cloudflare Service Workers + +**Preset:** `cloudflare` ([switch to this preset](/deploy/#changing-the-deployment-preset)) ::alert{type="info"} -**Note:** This preset uses [module syntax](https://developers.cloudflare.com/workers/learning/migrating-to-module-workers/) for deployment. +**Note:** This preset uses the [service worker syntax](https://developers.cloudflare.com/workers/learning/service-worker/) for deployment. :: -The module syntax allows you to use [Durable Objects](https://developers.cloudflare.com/workers/learning/using-durable-objects/), [D1](https://developers.cloudflare.com/d1/), and `waitUntil`. You can access the module bindings and context via `event.context.cloudflare`. - -For example, with the following additions to your `wrangler.toml`: - -```ini -services = [ - { binding = "WORKER", service = "" } -] -d1_databases = [ - { binding = "D1", database_id = "" } -] -``` - -### Using `waitUntil` - -`waitUntil` allows cache writes, external logging, etc without blocking the event. - -```ts -// waitUntil allows cache writes, external logging, etc without blocking the event -const { cloudflare } = event.context -cloudflare.context.waitUntil(logRequest(event.path)) -``` +::alert{type="warning"} +**Note:** This preset is deprecated. +:: -### Access env and bindings +The way this preset works is identical to that of the `cloudflare_module` one presented above, with the only difference being that such preset inherits all the [disadvantages](https://developers.cloudflare.com/workers/reference/migrate-to-module-workers/#advantages-of-migrating) that such syntax brings. -```js -const { cloudflare } = event.context -const res = await cloudflare.env.WORKER.fetch('') -``` +## Deploy within CI/CD using GitHub Actions -### D1 usage +Regardless on whether you're using Cloudflare Pages or Cloudflare workers, you can use the [Wrangler GitHub actions](https://github.com/marketplace/actions/deploy-to-cloudflare-workers-with-wrangler) to deploy your application. -```ts -const { cloudflare } = event.context -const stmt = await cloudflare.env.D1.prepare('SELECT id FROM table') -const { results } = await stmt.all() -``` +::alert{type="info"} +**Note:** Remember to [instruct Nitro to use the correct preset](/deploy/#changing-the-deployment-preset) (note that this is necessary for all presets including the `cloudflare_pages` one). +:: ## Environment Variables -Nitro allows to universally access environment variables using `process.env` or `import.meta.env` or runtime config. +Nitro allows you to universally access environment variables using `process.env` or `import.meta.env` or the runtime config. ::alert -Make sure to only access environment variables **within the event lifecycle** and not in global contexts since cloudflare only makes them available during the request lifecycle and not before. +Make sure to only access environment variables **within the event lifecycle** and not in global contexts since Cloudflare only makes them available during the request lifecycle and not before. :: -**Example:** If you have set `SECRET` and `NITRO_HELLO_THERE` environment variables you can access them with either of these: +**Example:** If you have set the `SECRET` and `NITRO_HELLO_THERE` environment variables set you can access them in the following way: ```ts -console.log(process.env.SECRET) // undefined (!) +console.log(process.env.SECRET) // note that this is in the global scope! so it doesn't actually work and the variable is undefined! export default defineEventHandler((event) => { - // These are valid: + // note that all the below are valid ways of accessing the above mentioned variables useRuntimeConfig(event).helloThere useRuntimeConfig(event).secret process.env.NITRO_HELLO_THERE @@ -249,7 +192,7 @@ export default defineEventHandler((event) => { }); ``` -#### Specify Variables in Development Mode +### Specify Variables in Development Mode For development, you can use a `.env` file to specify environment variables: @@ -259,22 +202,26 @@ SECRET="top-secret" ``` ::alert{type="info"} -**Note:** Make sure you add `.env` to the `.gitignore` file and do not commit it as it can contain sensitive information. +**Note:** Make sure you add `.env` to the `.gitignore` file so that you don't commit it as it can contain sensitive information. :: -#### Specify Variables for Preview +### Specify Variables for local previews + +After build, when you try out your project locally with `wrangler dev` or `wrangler pages dev`, in order to have access to environment variables you will need to specify the in a `.dev.vars` file in the root of your project (as presented in the [Pages](https://developers.cloudflare.com/pages/functions/bindings/#interact-with-your-environment-variables-locally) and [Workers](https://developers.cloudflare.com/workers/configuration/environment-variables/#interact-with-environment-variables-locally) documentation). +If you are using a `.env` file while developing, your `.dev.vars` should be identical to it. -After build, when you try out your project locally with `wrangler dev` or `wrangler pages dev`, use a `.dev.vars` file in the root of your project. +::alert{type="info"} +**Note:** Make sure you add `.dev.vars` to the `.gitignore` file so that you don't commit it as it can contain sensitive information. +:: -If you are using a `.env` file while developping, your `dev.vars` should be identical to it. -#### Specify Variables for Production +### Specify Variables for Production For production, use the cloudflare dashboard or the [`wrangler secret`](https://developers.cloudflare.com/workers/wrangler/commands/#secret) command to set environment variables and secrets. -#### Specify Variables using `wrangler.toml` +### Specify Variables using `wrangler.toml` You can specify a custom `wrangler.toml` file and define vars inside. @@ -300,26 +247,20 @@ NITRO_HELLO_THERE="captain" SECRET="top-secret" ``` -## Advanced +## Cloudflare Bindings -### Local Wrangler Dev builds +Bindings are what allows you to interact with resources from the Cloudflare platform, examples of such resources are key-value data storages ([KVs](https://developers.cloudflare.com/kv/)) and serverless SQL databases ([D1s](https://developers.cloudflare.com/d1/)). -By default `wrangler dev` requires nitro to be built before it can be served by wrangler. +For more details on Bindings and how to use them please refer to the Cloudflare [Pages](https://developers.cloudflare.com/pages/functions/bindings/) and [Workers](https://developers.cloudflare.com/workers/configuration/bindings/#bindings) documentation. -This can become tiresome if you're making changes to your nitro app and keep rebuilding to test changes in wrangler. +In your Nitro app you can access Cloudflare bindings from the request event, by accessing its `context.cloudflare.env` field, this is for example how you can access a D1 bindings: -::alert{type="warning"} -This is a temporary workaround until nitro has better support for wrangler dev mode! -:: - -To instruct wrangler to automatically rebuild nitro when it detects file changes, you need to add the following rule to your `wrangler.toml` file: - -```[wrangler.toml] -+ [env.development.build] -+ command = "NITRO_PRESET=cloudflare npm run build" // Replace npm with your package manager (npm, pnpm, yarn, bun) -+ cwd = "./" -+ watch_dir = ["./routes", "./nitro.config.ts"] +```ts +const { cloudflare } = event.context +const stmt = await cloudflare.env.MY_D1.prepare('SELECT id FROM table') +const { results } = await stmt.all() ``` -Now you need to run wrangler in development mode using `wrangler dev --env development` -When files change in nitro, wrangler will rebuild and serve the new files +::alert{type="warning"} +Note that bindings cannot be accessed during dev mode, they will be available only when you preview your Nitro app through `wrangler` or in the production deployment, and in both cases they need to be properly configured (as presented in the Cloudflare [Pages](https://developers.cloudflare.com/pages/functions/bindings/) and [Workers](https://developers.cloudflare.com/workers/configuration/bindings/#bindings) documentation). +:: From 1ac0116ac967d38306354536eb25cccd6f1b1b11 Mon Sep 17 00:00:00 2001 From: Pooya Parsa Date: Wed, 24 Jan 2024 00:42:24 +0100 Subject: [PATCH 3/4] Update 0.index.md --- docs/content/2.deploy/0.index.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/docs/content/2.deploy/0.index.md b/docs/content/2.deploy/0.index.md index a7d21bc957..5d85df1db6 100644 --- a/docs/content/2.deploy/0.index.md +++ b/docs/content/2.deploy/0.index.md @@ -6,11 +6,11 @@ icon: ri:upload-cloud-2-line Nitro can generate different output formats suitable for different hosting providers from the same code base. -Using built-in presets, you can easily configure Nitro to adjust it's output format with almost no additional code or configuration! +Using built-in presets, you can easily configure Nitro to adjust its output format with almost no additional code or configuration! ## Default output -Default production output preset is [Node.js server](/deploy/node). +The default production output preset is [Node.js server](/deploy/node). When running Nitro in development mode, Nitro will always use a special preset called `nitro-dev` using Node.js with ESM in an isolated Worker environment with behavior as close as possible to the production environment. @@ -27,25 +27,21 @@ When deploying to production using CI/CD, Nitro tries to automatically detect th - [vercel](/deploy/providers/vercel) - [zeabur](/deploy/providers/zeabur) -::alert{type="info"} -**Note:** Even with these presets, if you need to build your application locally (for development or testing purposes) targeting the provider environment, you still need to tell Nitro what preset it needs to use (you can see below how). -:: - ## Changing the deployment preset -If you need to build Nitro against a specific provider, you can target it by defining an environment variable named `NITRO_PRESET` or `SERVER_PRESET`, or by updating your Nitro [configuration](/guide/configuration). +If you need to build Nitro against a specific provider, you can target it by defining an environment variable named `NITRO_PRESET` or `SERVER_PRESET`, or by updating your Nitro [configuration](/guide/configuration) or using `--preset` argument. Using the environment variable approach is recommended for deployments depending on CI/CD. **Example:** Defining a `NITRO_PRESET` environment variable ```bash -NITRO_PRESET=aws_lambda nitro build +nitro build --preset cloudflare_pages ``` **Example:** Updating the `nitro.config.ts` file ```ts export default defineNitroConfig({ - preset: 'aws_lambda' + preset: 'cloudflare_pages' }) ``` From bd9278354b08ca16374c19f4ab93af41f4836337 Mon Sep 17 00:00:00 2001 From: Pooya Parsa Date: Wed, 24 Jan 2024 00:46:04 +0100 Subject: [PATCH 4/4] Update docs/content/2.deploy/20.providers/cloudflare.md --- docs/content/2.deploy/20.providers/cloudflare.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/2.deploy/20.providers/cloudflare.md b/docs/content/2.deploy/20.providers/cloudflare.md index c2f1dbd331..6dc92ffed3 100644 --- a/docs/content/2.deploy/20.providers/cloudflare.md +++ b/docs/content/2.deploy/20.providers/cloudflare.md @@ -80,7 +80,7 @@ npx wrangler pages deploy dist :: ::alert{type="warning"} -**Note:** This preset is deprecated. +**Note:** Using this preset is not recommended. :: When using Workers you will need a `wrangler.toml` file, in your root directory.