@vite-deploy/netlify

This adapter allows you to deploy your Vite project to Netlfy. Learn how in our Netlify deployment guide.

Netlify is a deployment platform that allows you to host your site by connecting directly to your GitHub repository. This adapter builds your Vite project for deployment through Netlify.

Installation

Starter template

1. Download a basic template for your favorite host:

   npx giget@latest gh:web-runes/vite-deploy/examples/netlify-server

2. Install dependencies:

   npm

   npm install

   pnpm

   pnpm install

   yarn

   yarn install

3. Start the development server:

   npm

   npm run dev

   pnpm

   pnpm dev

   yarn

   yarn dev

Manual install

1. Add @vite-deploy/netlify to your project’s dependencies using your preferred package manager:

   npm

   npm install @vite-deploy/netlify

   pnpm

   pnpm add @vite-deploy/netlify

   yarn

   yarn add @vite-deploy/netlify

2. Add the plugin to your Vite config file:

   vite.config.js

   import netlify from "@vite-deploy/netlify";
   import { defineConfig } from "vite";
   
   export default defineConfig({
     plugins: [netlify({
       output: "server",
       handlerEntrypoint: "./src/handler.ts",
     })]
   });

3. Update your TypeScript config file to include necessary types:

   tsconfig.json

   {
     "compilerOptions": {
       "types": [
         "vite/client",
         "@vite-deploy/netlify/types"
       ]
     },
   }

4. Create the handler entrypoint:

   src/handler.ts

   import type { ExportedHandler } from "@vite-deploy/netlify";
   
   export default {
     fetch(request) {
       const url = new URL(request.url);
       return new Response(`Running ${url.pathname} in ${navigator.userAgent}!`);
     },
   } satisfies ExportedHandler;

5. Start the development server:

   npm

   npm run dev

   pnpm

   pnpm dev

   yarn

   yarn dev

Options

The Netlify adapter accepts output related options. It also accepts the following:

handlerEntrypoint

Type: string | URL

Specifies what module should be used. It accepts:

• Paths relative to Vite’s root: ./src/handler.ts.
• Absolute paths: /foo/handler.ts.
• Package specifiers: @my-pkg/handler.
• URLs: new URL("./src/handler.ts", import.meta.url).

vite.config.js

import netlify from "@vite-deploy/netlify";
import { defineConfig } from "vite";

export default defineConfig({
    plugins: [netlify({
        // ...
        handlerEntrypoint: "./src/handler.ts",
    })]
});

The module must return a ExportedHandler, which handles requests:

src/handler.ts

import type { ExportedHandler } from "@vite-deploy/netlify";

export default {
  fetch(request, context) {
    const url = new URL(request.url);
    return new Response(`Running ${url.pathname} in ${navigator.userAgent}!`);
  },
} satisfies ExportedHandler;

config

Type: NetlifyPluginOptions | undefined
Default: undefined

Options forwarded to @netlify/vite-plugin, except middleware and build:

vite.config.js

import netlify from "@vite-deploy/netlify";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [netlify({
    // ...
    config: {
      blobs: { enabled: true },
    }
  })]
});

requestLoggingLevel

Type: "silent" | "info" | undefined
Default: "info"

Specifies if requests are logged in the terminal. It can be disabled if you already handle logging at runtime:

vite.config.js

import netlify from "@vite-deploy/netlify";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [netlify({
    // ...
    requestLoggingLevel: "silent"
  })]
});

Context

You can access Netlify-specific context in 2 ways:

• From the 2nd argument of handlerEntrypoint’s fetch handler:

  src/handler.ts

  import type { ExportedHandler } from "@vite-deploy/netlify";
  
  export default {
    fetch(request, context) {
      const url = new URL(request.url);
      return new Response(`Running ${url.pathname} in ${navigator.userAgent}!`);
    },
  } satisfies ExportedHandler;

• From the Netlify global:

  src/handler.ts

  import type { ExportedHandler } from "@vite-deploy/netlify";
  
  export default {
    fetch(request) {
      Netlify.context;
      const url = new URL(request.url);
      return new Response(`Running ${url.pathname} in ${navigator.userAgent}!`);
    },
  } satisfies ExportedHandler;

  Netlify.context is only set within request scope, otherwise it is null.

When not on Netlify nor used through the Netlify CLI, context properties are emulated.

Static assets

Static assets work out of the box. The adapter injects a header to cache assets under build.assetsDir.