From d3de7838f5a4b39a818d7c101ac6397fce3dfd20 Mon Sep 17 00:00:00 2001 From: James Culveyhouse Date: Thu, 8 Feb 2024 23:24:18 -0600 Subject: [PATCH] Update bindings section of qwik pages guide --- .../framework-guides/deploy-a-qwik-site.md | 120 ++++++++++++++---- 1 file changed, 95 insertions(+), 25 deletions(-) diff --git a/content/pages/framework-guides/deploy-a-qwik-site.md b/content/pages/framework-guides/deploy-a-qwik-site.md index 2e3a26d6399417..6e3ec42acee91f 100644 --- a/content/pages/framework-guides/deploy-a-qwik-site.md +++ b/content/pages/framework-guides/deploy-a-qwik-site.md @@ -9,60 +9,130 @@ title: Deploy a Qwik site In this guide, you will create a new Qwik application implemented via [Qwik City](https://qwik.builder.io/qwikcity/overview/) (Qwik's meta-framework) and deploy it using Cloudflare Pages. -## Creating a new project +## Creating a new project using C3 -Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to create a new project. C3 will create a new project directory, initiate Qwik's official setup tool, and provide the option to deploy instantly. - -To use `create-cloudflare` to create a new Qwik project, run the following command: +The easiest way to get started is by using the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (also known as C3). To do so, open a terminal and run: ```sh $ npm create cloudflare@latest my-qwik-app -- --framework=qwik ``` -`create-cloudflare` will install additional dependencies, including the [Wrangler CLI](/workers/wrangler/install-and-update/#check-your-wrangler-version) and any necessary adapters, and ask you setup questions. +C3 will create a new project with `create-qwik` (Qwik's official project creation tool) and install the necessary adapters along with the [Wrangler CLI](/workers/wrangler/install-and-update/#check-your-wrangler-version). + +## Migrating an existing Qwik application -As part of the `cloudflare-pages` adapter installation, a `functions/[[path]].ts` file will be created. The `[[path]]` filename indicates that this file will handle requests to all incoming URLs. Refer to [Path segments](/pages/functions/routing/#dynamic-routes) to learn more. +If you have an existing Qwik project which you'd like to deploy to Cloudflare, simply add the `cloudflare-pages` adapter via the `qwik` cli. -After selecting your server option, change the directory to your project and render your project by running the following command: +From the terminal, run the following command in your project directory: ```sh -$ npm start +$ npm run qwik add cloudflare-pages ``` -{{}} +Please refer to the documentation of the [Cloudflare Pages Adapter](https://qwik.dev/docs/deployments/cloudflare-pages/) for more information on basic configuration and support for advanced use cases. -{{}} +## Deploy your project -## Deploy with Cloudflare Pages +After creating your new project, C3 will give you the option of deploying an initial version of your application via [Direct Upload](/pages/how-to/use-direct-upload-with-continuous-integration/). You can re-deploy your application at any time by running following command inside your project directory: -{{}} +```sh +$ npm run deploy +``` -### Deploy via the Cloudflare dashboard +You can instead [connect a GitHub or Gitlab repository](/pages/configuration/git-integration) to your Pages project so that new versions of your project are built and deployed when changes to your git repository are detected. To do so, choose “No” when C3 asks if you’d like to deploy and refer to the guide below. -1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account. -2. In Account Home, select **Workers & Pages** > **Create application** > **Pages** > **Connect to Git**. -3. Select the new GitHub repository that you created and, in the **Set up builds and deployments** section, provide the following information: +{{}} -After configuring your site, you can begin your first deploy. You should see Cloudflare Pages installing `npm`, your project dependencies, and building your site before deploying it. +### Create a new GitHub repository + +Create a new GitHub repository by visiting [repo.new](https://repo.new). Next, prepare and push your local application to GitHub by running the following commands in your terminal: + +```sh +# Skip the following 3 commands if you've built your application +# using C3 or already committed your changes +$ git init +$ git add . +$ git commit -m "Initial commit" + +$ git branch -M main +$ git remote add origin https://github.com// +$ git push -u origin main +``` + +### Create a Pages project + +1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account. +2. Navigate to [Workers & Pages > Create application > Pages > Connect to Git](https://dash.cloudflare.com/?to=/:account/pages/new/provider/github) and create a new pages project. {{}} -After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`. -Every time you commit new code to your Qwik site, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, to preview how changes look to your site before deploying them to production. +You will be asked to authorize access to your GitHub account if you have not already done so. Cloudflare needs this so that it can monitor and deploy your projects from the source. You may narrow access to specific repositories if you prefer; however, you will have to manually update this list [within your GitHub settings](https://github.com/settings/installations) when you want to add more repositories to Cloudflare Pages. + +Select the new GitHub repository that you created and, in the **Set up builds and deployments** section, provide the following information: + +{{}} + +Optionally, you can customize the **Project name** field. It defaults to the GitHub repository's name, but it does not need to match. The **Project name** value is assigned as your `*.pages.dev` subdomain. + +After completing configuration, click the **Save and Deploy** button. -## Use bindings in your Qwik application +You will see your first deploy pipeline in progress. Pages installs all dependencies and builds the project as specified. + +Cloudflare Pages will automatically rebuild your project and deploy it on every new pushed commit. + +Additionally, you will have access to [preview deployments](/pages/configuration/preview-deployments/), which repeat the build-and-deploy process for pull requests. With these, you can preview changes to your project with a real URL before deploying them to production. + +## Bindings A [binding](/pages/functions/bindings/) allows your application to interact with Cloudflare developer products, such as [KV](/kv/reference/how-kv-works/), [Durable Object](/durable-objects/), [R2](/r2/), and [D1](https://blog.cloudflare.com/introducing-d1/). -In QwikCity, add server-side code via [routeLoaders](https://qwik.builder.io/qwikcity/route-loader/) and [actions](https://qwik.builder.io/qwikcity/action/). Then access bindings set for your application via the `platform` object provided by the framework. +If you intend to use bindings in your project, you must first set them up for local and remote development. + +Projects created via C3 come with a custom `vite` configuration that simplifies the process of working with bindings during development: + +```typescript +--- +filename: vite.config.ts +--- +// ... +let env = {}; + +if(process.env.NODE_ENV === 'development') { + const { getBindingsProxy } = await import('wrangler'); + const { bindings } = await getBindingsProxy(); + env = bindings; +} + +export default defineConfig((): UserConfig => { + return { + // .... + plugins: [ + qwikCity({ platform: { env } }), + // .... + ] + }; +}); +``` + +The `getBindingsProxy` [helper function](/workers/wrangler/api#getbindingsproxy) will automatically detect any bindings defined in the `wrangler.toml` file and emulate them in local development. See [Wrangler configuration](workers/wrangler/configuration/#bindings) for more information on how to configure bindings in `wrangler.toml`. + +{{}} + +In order to access bindings in a deployed application, you will need to [configure them](/pages/functions/bindings/) in the Cloudflare dashboard on your project's settings page. + +### Accessing bound resources in your application -The following code block shows an example of accessing a KV namespace in QwikCity. +In QwikCity, bindings can be accessed from server-side code via the `platform` object provided on [routeLoaders](https://qwik.builder.io/qwikcity/route-loader/) and [actions](https://qwik.builder.io/qwikcity/action/). The following code block shows an example of accessing a KV namespace in QwikCity. ```typescript --- @@ -81,4 +151,4 @@ export const useGetServerTime = routeLoader$(({ platform }) => { }); ``` -{{}} \ No newline at end of file +{{}}