@cryptoguard/manifest-tanstack-start

TanStack Start plugin for CryptoGuard manifest generation. Automatically generates a manifest file mapping your TanStack Start build output to served URL paths for binary transparency verification.

Installation

pnpm add @cryptoguard/manifest-tanstack-start

Usage

Add the plugin to your vite.config.ts:

import { defineConfig } from 'vite';
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import viteReact from '@vitejs/plugin-react';
import { nitroV2Plugin } from '@tanstack/nitro-v2-vite-plugin';
import { cryptoGuardManifest } from '@cryptoguard/manifest-tanstack-start';

export default defineConfig({
  plugins: [
    nitroV2Plugin(),
    tanstackStart(),
    viteReact(),
    cryptoGuardManifest()
  ]
});

Configuration

With TanStack Start Config

Pass your configuration to the plugin:

import { defineConfig } from 'vite';
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import { cryptoGuardManifest } from '@cryptoguard/manifest-tanstack-start';

const tanstackConfig = {
  base: '/docs'
};

export default defineConfig({
  base: tanstackConfig.base,
  plugins: [
    tanstackStart(),
    cryptoGuardManifest(tanstackConfig)
  ]
});

Plugin Options

cryptoGuardManifest(tanstackConfig, {
  verbose: true,   // Enable detailed logging
  disabled: false, // Disable manifest generation
  projectRoot: process.cwd() // Project root directory
})

Environment Variables

You can use environment variables for dynamic configuration:

const tanstackConfig = {
  base: process.env.PUBLIC_BASE_PATH || ''
};

export default defineConfig({
  base: tanstackConfig.base || undefined,
  plugins: [
    tanstackStart(),
    cryptoGuardManifest(tanstackConfig, {
      verbose: process.env.MANIFEST_VERBOSE === 'true',
      disabled: process.env.MANIFEST_DISABLED === 'true'
    })
  ]
});

Generated Manifest

The plugin generates a manifest.json file in your project root:

{
  "version": "1.0",
  "framework": "tanstack-start",
  "frameworkVersion": "1.132.0",
  "sources": [
    {
      "dir": ".output/public",
      "serveAt": "/"
    }
  ]
}

With Base Path

When using base configuration:

{
  "version": "1.0",
  "framework": "tanstack-start",
  "frameworkVersion": "1.132.0",
  "sources": [
    {
      "dir": ".output/public",
      "serveAt": "/docs"
    }
  ]
}

How It Works

1. Build Hook: Runs after TanStack Start build completes (closeBundle)
2. Path Detection: Extracts base and outDir from your config
3. Manifest Generation: Maps .output/public/ to the appropriate serve path
4. Smart Updates: Only updates manifest.json when content changes
5. Validation: Ensures manifest security (no path traversal, proper structure)

TanStack Start Build Output Structure

TanStack Start (with Nitro) generates:

• .output/public/ - All client-side assets
• .output/public/assets/ - Bundled JavaScript and CSS (hashed filenames)
• .output/server/ - Server-side rendering code (not served to clients)

The plugin maps the .output/public/ directory to your configured base path, as TanStack Start serves all client assets (including assets/ subdirectory) from this location.

URL Mapping Example

File on Disk                              URL in Browser
──────────────────────────────────────────────────────────────
.output/public/assets/main-DzvKBgP-.js  → /assets/main-DzvKBgP-.js
.output/public/assets/styles-D0UYo-87.css → /assets/styles-D0UYo-87.css
.output/public/favicon.ico              → /favicon.ico
.output/public/logo192.png              → /logo192.png

With base: "/docs":

.output/public/assets/main.js → /docs/assets/main.js
.output/public/favicon.ico    → /docs/favicon.ico

License

MIT