@cloudflare/vite-plugin 0.0.0-e2f5756c2 → 0.0.0-e5dbedd78

package/README.md

@@ -1,6 +1,6 @@
 # `@cloudflare/vite-plugin`
 
-[Intro](#intro) | [Quick start](#quick-start) | [Tutorial](#tutorial) | [API](#api) | [Cloudflare environments](#worker-environments) | [Migrating from `wrangler dev`](#migrating-from-wrangler-dev)
+[Intro](#intro) | [Quick start](#quick-start) | [Tutorial](#tutorial) | [API](#api) | [Cloudflare environments](#cloudflare-environments) | [Debugging](#debugging) | [Migrating from `wrangler dev`](#migrating-from-wrangler-dev)
 
 ## Intro
 
@@ -16,23 +16,42 @@ Your Worker code runs inside [workerd](https://github.com/cloudflare/workerd), m
 
 ## Quick start
 
+### Start with a basic `package.json`
+
+```json
+{
+  "name": "cloudflare-vite-quick-start",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  }
+}
+```
+
+> [!NOTE]
+> Ensure that you include `"type": "module"` in order to use ES modules by default.
+
 ### Install the dependencies
 
 ```sh
-npm install @cloudflare/vite-plugin wrangler --save-dev
+npm install vite @cloudflare/vite-plugin wrangler --save-dev
 ```
 
-### Add the plugin to your Vite config
+### Create your Vite config file and include the Cloudflare plugin
 
 ```ts
 // vite.config.ts
 
-import { defineConfig } from 'vite'
-import { cloudflare } from '@cloudflare/vite-plugin'
+import { defineConfig } from "vite";
+import { cloudflare } from "@cloudflare/vite-plugin";
 
 export default defineConfig({
   plugins: [cloudflare()],
-})
+});
 ```
 
 ### Create your Worker config file
@@ -40,7 +59,7 @@ export default defineConfig({
 ```toml
 # wrangler.toml
 
-name = "my-worker"
+name = "cloudflare-vite-quick-start"
 compatibility_date = "2024-12-30"
 main = "./src/index.ts"
 ```
@@ -52,12 +71,12 @@ main = "./src/index.ts"
 
 export default {
   fetch() {
-    return new Response(`Running in ${navigator.userAgent}!`)
+    return new Response(`Running in ${navigator.userAgent}!`);
   },
-}
+};
 ```
 
-You can now develop (`vite dev`), build (`vite build`), preview (`vite preview`), and deploy (`wrangler deploy`) your application.
+You can now develop (`npm run dev`), build (`npm run build`), preview (`npm run preview`), and deploy (`npm exec wrangler deploy`) your application.
 
 ## Tutorial
 
@@ -88,13 +107,13 @@ npm install @cloudflare/vite-plugin wrangler --save-dev
 ```ts
 // vite.config.ts
 
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import { cloudflare } from '@cloudflare/vite-plugin'
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { cloudflare } from "@cloudflare/vite-plugin";
 
 export default defineConfig({
   plugins: [react(), cloudflare()],
-})
+});
 ```
 
 #### Create your Worker config file
@@ -121,6 +140,15 @@ The `directory` in the output configuration will automatically point to the clie
 > This output file is a snapshot of your configuration at the time of the build and is modified to reference your build artifacts.
 > It is the configuration that is used for preview and deployment.
 
+#### Update the .gitignore file
+
+Wrangler will use and/or generate temporary files that should not be stored in git. Add the following lines to the `.gitignore` file:
+
+```gitignore
+.wrangler
+.dev.vars
+```
+
 #### Run the development server
 
 Run `npm run dev` to verify that your application is working as expected.
@@ -181,22 +209,22 @@ The assets `binding` defined here will allow you to access the assets functional
 // api/index.ts
 
 interface Env {
-  ASSETS: Fetcher
+  ASSETS: Fetcher;
 }
 
 export default {
   fetch(request, env) {
-    const url = new URL(request.url)
+    const url = new URL(request.url);
 
-    if (url.pathname.startsWith('/api/')) {
+    if (url.pathname.startsWith("/api/")) {
       return Response.json({
-        name: 'Cloudflare',
-      })
+        name: "Cloudflare",
+      });
     }
 
-    return env.ASSETS.fetch(request)
+    return env.ASSETS.fetch(request);
   },
-} satisfies ExportedHandler<Env>
+} satisfies ExportedHandler<Env>;
 ```
 
 The Worker above will be invoked for any request not matching a static asset.
@@ -211,14 +239,14 @@ Replace the file contents with the following code:
 ```tsx
 // src/App.tsx
 
-import { useState } from 'react'
-import reactLogo from './assets/react.svg'
-import viteLogo from '/vite.svg'
-import './App.css'
+import { useState } from "react";
+import reactLogo from "./assets/react.svg";
+import viteLogo from "/vite.svg";
+import "./App.css";
 
 function App() {
-  const [count, setCount] = useState(0)
-  const [name, setName] = useState('unknown')
+  const [count, setCount] = useState(0);
+  const [name, setName] = useState("unknown");
 
   return (
     <>
@@ -245,9 +273,9 @@ function App() {
       <div className="card">
         <button
           onClick={() => {
-            fetch('/api/')
+            fetch("/api/")
               .then((res) => res.json() as Promise<{ name: string }>)
-              .then((data) => setName(data.name))
+              .then((data) => setName(data.name));
           }}
           aria-label="get name"
         >
@@ -261,10 +289,10 @@ function App() {
         Click on the Vite and React logos to learn more
       </p>
     </>
-  )
+  );
 }
 
-export default App
+export default App;
 ```
 
 Now, if you click the button, it will display 'Name from API is: Cloudflare'.
@@ -310,12 +338,12 @@ The `cloudflare` plugin should be included in the Vite `plugins` array:
 ```ts
 // vite.config.ts
 
-import { defineConfig } from 'vite'
-import { cloudflare } from '@cloudflare/vite-plugin'
+import { defineConfig } from "vite";
+import { cloudflare } from "@cloudflare/vite-plugin";
 
 export default defineConfig({
   plugins: [cloudflare()],
-})
+});
 ```
 
 It accepts an optional `PluginConfig` parameter.
@@ -346,6 +374,10 @@ It accepts an optional `PluginConfig` parameter.
   All requests are routed through your entry Worker.
   During the build, each Worker is output to a separate subdirectory of `dist`.
 
+- `inspectorPort?: number | false`
+
+  Optional inspector port to use for debugging your workers, for more details on debugging see the [devtools section](#devtools). Can be set to `false` to disable the debugging inspector altogether. Defaults to `9229`.
+
 > [!NOTE]
 > When running `wrangler deploy`, only your main (entry) Worker will be deployed.
 > If using multiple Workers, each must be deployed individually.
@@ -447,6 +479,69 @@ The value of `MY_VAR` will therefore be `'Production var'`.
 If you run `vite build --mode staging` then the 'staging' Vite mode will be used and the 'staging' Cloudflare environment will be selected.
 The value of `MY_VAR` will therefore be `'Staging var'`.
 
+## Secrets
+
+Secrets can be provided to your Worker in local development using a [`.dev.vars`](https://developers.cloudflare.com/workers/configuration/secrets/#local-development-with-secrets) file. If you are using [Cloudflare Environments](#cloudflare-environments) then the relevant `.dev.vars` file will be selected. For example, `CLOUDFLARE_ENV=staging vite dev` will load `.dev.vars.staging` if it exists and fall back to `.dev.vars`.
+
+> [!NOTE]
+> The `vite build` command copies the relevant `.dev.vars[.env-name]` file to the output directory. This is only used when running `vite preview` and is not deployed with your Worker.
+
+## Debugging
+
+The Cloudflare Vite plugin allows you to conveniently debug your Worker code during local development.
+
+By default the inspector port used by the plugin is `9229`, which can be customized by providing a different port to the plugin's `inspectorPort` option.
+
+There are two recommended ways of doing so, which we'll explore in this section.
+
+### Devtools
+
+When running `vite dev` or `vite preview` a `/__debug` route in your local server will be made available which gives you access to [Cloudflare's implementation](/packages/chrome-devtools-patches) of [Chrome's DevTools](https://developer.chrome.com/docs/devtools/overview).
+
+Navigating to this route will open a devtools tab for each of the workers in your application (Note: in case of multiple workers you might need to allow your browser to open pop-ups).
+
+Once the tab or tabs are open, you can make a request to your application and start debugging your workers' code.
+
+Note: If you're not interested in debugging all your workers you can close the tabs of the workers you don't want to debug.
+
+### VS Code
+
+To setup VS Code for breakpoint debugging for your application, you will need to create a `.vscode/launch.json` file that contains a configuration following this structure:
+
+```json
+{
+  "configurations": [
+    {
+      "name": "<NAME_OF_WORKER>",
+      "type": "node",
+      "request": "attach",
+      "websocketAddress": "ws://localhost:9229/<NAME_OF_WORKER>",
+      "resolveSourceMapLocations": null,
+      "attachExistingChildren": false,
+      "autoAttachChildProcesses": false,
+      "sourceMaps": true
+    }
+  ],
+  "compounds": [
+    {
+      "name": "Debug All Workers",
+      "configurations": ["<NAME_OF_WORKER>"],
+      "stopAll": true
+    }
+  ]
+}
+```
+
+Where, `<NAME_OF_WORKER>` indicates the name of your worker as specified in your Wrangler configuration.
+
+Note: if you customized your `inspectorPort` you need to use that port in the `websocketAddress` field.
+
+If you have more than one worker you need add a configuration in the `configurations` field for each one and then include the configuration name in the `configurations` array in the compound configuration.
+
+Once your `launch.json` file is ready, after running `vite dev` or `vite preview` you can select **Debug All Workers** at the top of the **Run & Debug** panel to attach debuggers to all the various Workers. Then you can add breakpoints to your code and start debugging.
+
+Note: You can also manually select the configurations to run (e.g. **Debug Worker1**) to filter which workers you want to debug.
+
 ## Migrating from `wrangler dev`
 
 Migrating from `wrangler dev` is a simple process and you can follow the instructions in the [Quick start](#quick-start) to get started.