@cryptoguard/manifest-nextjs

Next.js plugin for CryptoGuard manifest generation. Enables binary transparency verification for Next.js applications.

Installation

npm install --save-dev @cryptoguard/manifest-nextjs
# or
pnpm add -D @cryptoguard/manifest-nextjs
# or
yarn add -D @cryptoguard/manifest-nextjs

Quick Start

1. Wrap Your Next.js Config

// next.config.ts
import { withCryptoGuardManifest } from '@cryptoguard/manifest-nextjs';

const config = {
  // Your Next.js configuration
  distDir: '.next',
  basePath: '',
  // ... other options
};

export default withCryptoGuardManifest(config);

2. Build Your Application

npm run build

The plugin will automatically generate manifest.json in your project root.

3. Commit the Manifest

git add manifest.json next.config.ts
git commit -m "Add CryptoGuard manifest"

How It Works

The plugin wraps your Next.js configuration and:

1. Reads your config values (distDir, basePath, etc.)
2. Detects Next.js version from package.json
3. Generates manifest.json with source mappings
4. Writes to project root (only if changed)
5. Returns your config unchanged (Next.js proceeds normally)

Generated Manifest

Example manifest.json:

{
  "version": "1.0",
  "framework": "nextjs",
  "frameworkVersion": "15.0.0",
  "sources": [
    {
      "dir": ".next/static",
      "serveAt": "/_next/static"
    },
    {
      "dir": "public",
      "serveAt": "/"
    }
  ]
}

Supported Configurations

Custom Build Directory

const config = {
  distDir: 'build', // Custom build directory
};

export default withCryptoGuardManifest(config);

Generated manifest:

{
  "sources": [
    { "dir": "build/static", "serveAt": "/_next/static" },
    { "dir": "public", "serveAt": "/" }
  ]
}

Base Path

const config = {
  basePath: '/docs', // Deploy in subdirectory
};

export default withCryptoGuardManifest(config);

Generated manifest:

{
  "sources": [
    { "dir": ".next/static", "serveAt": "/docs/_next/static" },
    { "dir": "public", "serveAt": "/docs" }
  ]
}

Advanced Usage

Debug Mode

Enable verbose logging:

import { withCryptoGuardManifestDebug } from '@cryptoguard/manifest-nextjs';

export default withCryptoGuardManifestDebug(config);

Custom Options

import { withCryptoGuardManifest } from '@cryptoguard/manifest-nextjs';

export default withCryptoGuardManifest(config, {
  verbose: true,           // Enable logging
  projectRoot: process.cwd(), // Custom project root
  disabled: false,         // Disable manifest generation
});

Programmatic Usage

import { generateManifest, validateManifest } from '@cryptoguard/manifest-nextjs';

const manifest = generateManifest({
  distDir: '.next',
  basePath: '',
});

validateManifest(manifest); // Throws if invalid
console.log(manifest);

Requirements

• Node.js: ≥18.0.0
• Next.js: ≥15.0.0 (officially supported)
• TypeScript: ≥5.0.0 (recommended)

Limitations

Not Yet Supported

The following Next.js features are not yet supported in v0.1.0:

• ✗ assetPrefix (CDN hosting) - Will be added in future version
• ✗ Custom server - May require manual manifest
• ✗ Standalone output - Not tested yet

A warning will be displayed if these are detected.

Supported Versions

| Next.js Version | Support Status | |----------------|----------------| | 15.x | ✅ Fully supported | | 14.x | ⚠️ May work (not tested) | | 13.x | ⚠️ May work (not tested) | | 12.x and below | ❌ Not supported |

Troubleshooting

Manifest Not Generated

Problem: No manifest.json created after build.

Solution:

1. Ensure you're using withCryptoGuardManifest wrapper
2. Check for error messages during build
3. Try debug mode: withCryptoGuardManifestDebug(config)

Build Fails

Problem: Build fails with manifest error.

Solution:

1. Check error message in console
2. Verify Next.js version is ≥15.0.0
3. Ensure package.json contains Next.js dependency
4. Try disabling manifest: withCryptoGuardManifest(config, { disabled: true })

Manifest Not Updated

Problem: Manifest doesn't update after config change.

Solution:

• The plugin only updates manifest when it detects changes
• Try deleting manifest.json and rebuilding
• Check that config changes are actually applied

API Reference

withCryptoGuardManifest(config, options?)

Wraps Next.js config to generate manifest.

Parameters:

• config: NextConfig - Next.js configuration object
• options?: ManifestOptions - Optional generation options

Returns: NextConfig - Original config (unchanged)

withCryptoGuardManifestDebug(config)

Alias for withCryptoGuardManifest with verbose logging.

generateManifest(config, options?)

Generate manifest without writing to disk.

Returns: Manifest - Generated manifest object

validateManifest(manifest)

Validate manifest structure.

Throws: Error if manifest is invalid

detectNextVersion(projectRoot?)

Detect Next.js version from package.json.

Returns: string - Next.js version (e.g., "15.0.0")

Contributing

Issues and pull requests are welcome!

License

MIT

Links

• CryptoGuard Documentation
• GitHub Repository
• npm Package

Built by the CryptoGuard Team