Feat/docs (#3)

.github/workflows/release.yml

@@ -10,7 +10,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
-        with: 
+        with:
           node-version: "20"
       - run: corepack enable
       - run: pnpm install
@@ -24,14 +24,6 @@ jobs:
           retention-days: 30
           path: packages/vite-plugin-hash-csp/dist
 
-      # - name: Build Documentation Site
-      #   run: npm run docs:build
-      # - name: Upload artifact
-      #   uses: actions/upload-pages-artifact@v3
-      #   with:
-      #     path: ./apps/docs/out
-
-
   publish:
     runs-on: ubuntu-latest
     needs: build_and_test
@@ -65,7 +57,7 @@ jobs:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           custom_tag: v${{steps.publish.outputs.version}}
           tag_prefix: vite-plugin-csp-hash_
-          
+
       - name: Create a GitHub release
         if: ${{ steps.publish.outputs.type }}
         uses: ncipollo/release-action@v1
@@ -75,17 +67,35 @@ jobs:
           body: ${{ steps.tag_version.outputs.changelog }}
           generateReleaseNotes: true
 
-  # deploy:
-  #   runs-on: ubuntu-latest
-  #   needs: build_and_test
-  #   permissions: 
-  #     contents: read
-  #     pages: write
-  #     id-token: write
-  #   environment:
-  #     name: github-pages
-  #     url: ${{ steps.deployment.outputs.page_url }}
-  #   steps:
-  #     - name: Deploy to GitHub Pages
-  #       id: deployment
-  #       uses: actions/deploy-pages@v4
+  build_docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - run: corepack enable
+      - run: pnpm install --filter docs
+      - name: Build Documentation Site
+        run: pnpm docs:build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./apps/docs/out
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build_docs
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

apps/docs/next-env.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/basic-features/typescript for more information.

apps/docs/next-sitemap.config.js

@@ -0,0 +1,26 @@
+/** @type {import('next-sitemap').IConfig} */
+module.exports = {
+  siteUrl: "https://vite-posthog.tsotne.co.uk",
+  generateRobotsTxt: true, // (optional)
+  generateIndexSitemap: false,
+  sitemapSize: 100,
+  output: "export",
+  additionalPaths: async () => [
+    {
+      loc: "/",
+      priority: "1.0",
+    },
+    {
+      loc: "/getting-started",
+      priority: 0.9,
+    },
+    {
+      loc: "/react/core",
+      priority: 0.6,
+    },
+    {
+      loc: "/react/feature-flags",
+      priority: 0.6,
+    },
+  ],
+};

apps/docs/next.config.js

@@ -0,0 +1,17 @@
+/** @type {import('next').NextConfig} */
+
+const withNextra = require("nextra")({
+  theme: "nextra-theme-docs",
+  themeConfig: "./theme.config.jsx",
+});
+
+module.exports = withNextra({
+  reactStrictMode: true,
+  output: "export",
+  images: {
+    unoptimized: true,
+  },
+});
+
+// If you have other Next.js configurations, you can pass them as the parameter:
+// module.exports = withNextra({ /* other next.js config */ })

apps/docs/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "docs",
+    "version": "0.1.0",
+    "private": true,
+    "scripts": {
+        "dev": "next dev",
+        "build": "next build",
+        "postbuild": "next-sitemap",
+        "preview": "npx serve out -p 3000",
+        "lint": "next lint"
+    },
+    "dependencies": {
+        "copy-to-clipboard": "^3.3.3",
+        "framer-motion": "^11.0.5",
+        "next": "latest",
+        "next-sitemap": "^4.2.3",
+        "nextra": "^2.13.3",
+        "nextra-theme-docs": "^2.13.3",
+        "react": "latest",
+        "react-dom": "latest"
+    },
+    "devDependencies": {
+        "@types/node": "latest",
+        "@types/react": "latest",
+        "eslint": "^8.0.0",
+        "eslint-config-next": "latest",
+        "typescript": "latest"
+    }
+}

apps/docs/pages/_document.tsx

@@ -0,0 +1,17 @@
+import { Html, Head, Main, NextScript } from "next/document";
+
+export default function MyDocument() {
+  return (
+    <Html lang="en">
+      <Head>
+        {/* PWA primary color */}
+        <link rel="shortcut icon" href="/vite_logo.svg" />
+        <meta name="emotion-insertion-point" content="" />
+      </Head>
+      <body>
+        <Main />
+        <NextScript />
+      </body>
+    </Html>
+  );
+}

apps/docs/pages/_meta.json

@@ -0,0 +1,10 @@
+{
+  "index": {
+    "title": "Home",
+    "href": "/"
+  },
+  "guides": {
+    "title": "Guides",
+    "href": "/guides"
+  }
+}

apps/docs/pages/guides/_meta.json

@@ -0,0 +1,10 @@
+{
+    "spa": {
+        "title": "SPA",
+        "href": "/guides/spa"
+    },
+    "mpa": {
+        "title": "MPA",
+        "href": "/guides/mpa"
+    }
+}

apps/docs/pages/guides/mpa.mdx

@@ -0,0 +1,10 @@
+import {Callout} from "nextra-theme-docs";
+
+# MPA
+This plugin currently does not support Multi Page Applications (MPA).
+
+<Callout type="info">
+    Support for this is planned in the future.
+</Callout>
+
+Highly recommend checking out Vite's [inbuilt nonce support](https://vitejs.dev/guide/features#content-security-policy-csp) for CSPs. 

apps/docs/pages/guides/spa.mdx

@@ -0,0 +1,76 @@
+import { Tabs, Callout } from "nextra-theme-docs"
+
+# SPA 
+
+This plugin provides 1st class support for Single Page Applications (SPA).
+
+## What problem does this plugin solve?
+The issue with SPA's is that they don't have a server that the application runs on to generate a unique `nonce` for each request. This means that you can't use [nonce based CSPs](https://content-security-policy.com/nonce/). 
+This plugin solves this issue by using the alternative [hash based CSP](https://content-security-policy.com/hash/) instead, which is the only way to secure your SPA without a server.
+
+## Installation
+
+<Tabs items={['npm', 'yarn', 'pnpm']} defaultIndex="1">
+  <Tabs.Tab>
+  ```bash
+npm install vite-plugin-hash-csp
+  ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+  ```bash 
+yarn add vite-plugin-hash-csp
+    ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+  ```bash
+pnpm add vite-plugin-hash-csp
+  ```
+  </Tabs.Tab>
+</Tabs>
+
+
+## Usage
+
+```ts
+
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import csp from "vite-plugin-hash-csp";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [
+    react(),
+    csp({
+      algorithm: "sha256",  // Pick your hashing algorithm
+      runOnDev: true,   // Run on `vite dev`
+      policy: {
+        "script-src": ["'self'", "https://www.google-analytics.com"],    //Allow google analytics to run
+        "font-src": ["'self'", "https://fonts.gstatic.com"],    //Allows fonts from Google to load
+      }
+    }),
+  ],
+});
+
+```
+
+
+### Caveats
+
+If you are using a library that dynamically injects css into the page (e.g. `styled-components`, `emotion`, or `MUI`), you will need to set your `style-elem-src` policy to include `'unsafe-inline'`.
+
+The only other alternative is to move to a server and use nonce based CSPs.
+
+We are actively working to find a solution to this [issue](https://github.com/RockiRider/vite-plugin-hash-csp/issues/2), and there isn't much support for hash based CSPs in those libraries yet.
+
+<Callout type="warning">
+    There are risks to using `'unsafe-inline'` for your styles. But most of these can be mitigated by the rest of the CSP. [Read more about this here](https://scotthelme.co.uk/can-you-get-pwned-with-css/)
+</Callout>
+
+
+## Maintenance 
+
+This is one of the most difficult parts of CSPs. They are very easy to get wrong, and can break your site if you aren't careful.
+- Adding `vite dev` support via `runOnDev` flag is a great way to test your new third party scripts work before deploying it to production.
+- We will be developing eslint rules to help you catch common mistakes in your CSPs. Watch this space!
+

apps/docs/pages/index.mdx

@@ -0,0 +1,18 @@
+import { Tab, Tabs, Cards, Card } from "nextra-theme-docs";
+
+# Vite Plugin Hash CSP
+This is a **Vite plugin** that lets you quickly add a Content Security Policy (CSP) to your Vite project. Whilst CSPs are a great way to protect your site from XSS attacks, they can be a pain to set up correctly and maintain. 
+This plugin aims to solve these pain points.
+
+
+## Getting Started
+
+We have 2 seperate guides for Single Page Applications (SPA) and Multi Page Applications (MPA). Choose the one that best fits your project.
+
+<Cards>
+  <Card title="SPA" href="/guides/spa" />
+  <Card title="MPA" href="/guides/mpa" />
+</Cards>
+
+
+

apps/docs/theme.config.jsx

@@ -0,0 +1,34 @@
+export default {
+  logo: <span style={{ fontWeight: 600 }}>Vite Posthog</span>,
+  project: {
+    link: "https://github.com/RockiRider/vite-plugin-posthog",
+  },
+  docsRepositoryBase:
+    "https://github.com/RockiRider/vite-plugin-posthog/tree/main/apps/docs",
+  useNextSeoProps() {
+    return {
+      titleTemplate: "%s | Vite Posthog",
+      description: "Vite Posthog",
+      openGraph: {
+        description: "A vite integration with Posthog",
+        siteName: "Vite Posthog",
+      },
+      twitter: {},
+    };
+  },
+  head: <></>,
+  feedback: {
+    content: null,
+  },
+  footer: {
+    text: (
+      <span>
+        MIT {new Date().getFullYear()} ©{" "}
+        <a href="https://vite-posthog.tsotne.co.uk" target="_blank">
+          Vite Posthog
+        </a>
+        .
+      </span>
+    ),
+  },
+};

apps/docs/tsconfig.json

@@ -0,0 +1,25 @@
+{
+    "extends": "@repo/typescript-config/nextjs.json",
+    "compilerOptions": {
+      "plugins": [
+        {
+          "name": "next"
+        }
+      ],
+      "baseUrl": ".",
+      "paths": {
+        "@components/*": ["src/components/*"],
+        "@styles/*": ["src/styles/*"],
+        "@features/*": ["src/features/*"],
+      }
+    },
+    "include": [
+      "next-env.d.ts",
+      "next.config.js",
+      "**/*.ts",
+      "**/*.tsx",
+      ".next/types/**/*.ts"
+, "pages/index.mdx",    ],
+    "exclude": ["node_modules"]
+  }
+