Creating your policy

This will hopefully help you build your CSP policy.

Defining your policy with type-safe primitives (recommended)

Vite Plugin CSP Guard uses csp-toolkit (opens in a new tab) under the hood. From csp-toolkit 1.5, use definePolicy with camelCase directive keys and small helpers for keywords and schemes. The library turns those into the quoted source expressions the browser expects (for example 'self', data:).

import { defineConfig } from "vite"
import react from "@vitejs/plugin-react"
import csp from "vite-plugin-csp-guard"
import { definePolicy, self, data } from "csp-toolkit"
 
export default defineConfig({
  plugins: [
    react(),
    csp({
      policy: definePolicy({
        defaultSrc: [self],
        imgSrc: [self, data],
        scriptSrc: ["https://www.google-analytics.com"],
      }),
    }),
  ],
})

You can still use a plain object with kebab-case keys and string sources if you prefer; both shapes are valid for the policy option. See the V4 migration notes for a before/after comparison.

Default Policies

We do this so you don't have to worry about the basics. These are merged with your custom policies.

In csp-toolkit terms, the build defaults are equivalent to:

import { definePolicy, self } from "csp-toolkit"
 
definePolicy({
  defaultSrc: [self],
  imgSrc: [self],
  scriptSrcElem: [self],
  styleSrcElem: [self],
})

(As raw directive strings, the same idea is:)

"default-src": ["'self'"],
"img-src": ["'self'"],
"script-src-elem": ["'self'"],
"style-src-elem": ["'self'"],

You can override these defaults if you wish via the override flag

In dev mode data (the data: scheme) is added to imgSrc for your convenience

Typical use cases

Third party javascript

Third party code like, Google Analytics, Hotjar, etc. are common in most websites. You can use the scriptSrc directive to allow these scripts to run.

⚠️

When doing this you are essentially trusting third party code to run on your website. Make sure you trust these third parties as you are explicitly giving them permission to run code on your site

 
import { defineConfig, PluginOption } from "vite";
import react from "@vitejs/plugin-react";
import csp from "vite-plugin-csp-guard";
import { definePolicy } from "csp-toolkit";
 
// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    react(),
    csp({
        policy: definePolicy({
            scriptSrc: ["https://www.google-analytics.com"],
        }),
    }),
  ],
});

Targetting a specific domain is a good way to ensure that only scripts from that domain are allowed to run. Sometimes its even better to be more specific and target a specific path on that domain, aslong as the path is unique and constant.

Third party css

Third party styles, that are injected at runtime are also common in most websites. You can use the styleSrc directive to allow these styles to be applied.

 
import { defineConfig, PluginOption } from "vite";
import react from "@vitejs/plugin-react";
import csp from "vite-plugin-csp-guard";
import { definePolicy } from "csp-toolkit";
 
// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    react(),
    csp({
        policy: definePolicy({
            styleSrc: ["https://example.com/styles/main.css"],
        }),
    }),
  ],
});

Full list of directives

The full list can be found here (opens in a new tab)

MPA V2