Docs Menu
API
Get Started
Edit this page

@photonjs/runtime

@photonjs/runtime

Beta

The runtime package provides convenience functions for framework developers to integrate Photon.

npm install @photonjs/runtime

Exports

./vite

Vite integration functions for framework developers.

import { installPhoton } from '@photonjs/runtime/vite'

Functions

installPhoton(frameworkName, config?)

Install Photon with framework-specific configuration.

function installPhoton(
  frameworkName: string,
  config?: RuntimeConfig
): Plugin[]

Parameters:

  • frameworkName - Unique identifier for your framework
  • config - Optional runtime configuration

Returns: Array of Vite plugins

Example:

import { installPhoton } from '@photonjs/runtime/vite'
 
export function myFrameworkPlugin(): Plugin[] {
  return installPhoton('my-framework', {
    fullInstall: true,
    resolveMiddlewares: () => 'my-framework/universal-middleware'
  })
}

Configuration

RuntimeConfig

Configuration interface for framework integration.

interface RuntimeConfig {
  fullInstall?: boolean
  codeSplitting?: CodeSplittingConfig
  resolveMiddlewares?: () => string
  entries?: Record<string, EntryConfig>
}

fullInstall

Enable all Photon features.

// Enable all features (recommended)
fullInstall: true
 
// Minimal installation
fullInstall: false

codeSplitting

Configure code splitting behavior.

interface CodeSplittingConfig {
  framework?: boolean
  target?: boolean
}

Example:

codeSplitting: {
  framework: false, // Disable framework-level splitting
  target: true      // Enable per-route splitting when supported by target
}

resolveMiddlewares

Function that returns the middleware module path.

// Static middleware path
resolveMiddlewares: () => 'my-framework/universal-middleware'
 
// Dynamic resolution
resolveMiddlewares: (context) => {
  return context.isDevelopment
    ? 'my-framework/dev-middleware'
    : 'my-framework/prod-middleware'
}

entries

Define framework-specific entry points.

interface EntryConfig {
  id: string
  compositionMode?: 'auto' | 'isolated'
}

Example:

entries: {
  standalone: {
    id: 'my-framework/standalone',
    compositionMode: 'isolated'
  },
 
  api: {
    id: 'my-framework/api'
  }
}

Entry Configuration

Composition Modes

auto (default): Entry is composed with framework middleware from resolveMiddlewares().

isolated: Entry runs independently without framework middleware composition.

Integration Patterns

Simple Framework

Minimal integration for basic frameworks:

export function simpleFramework(): Plugin[] {
  return installPhoton('simple', {
    resolveMiddlewares: () => 'simple/middleware'
  })
}

Refer to vike-photon for a complete integration example.

Examples

Framework Plugin

// src/vite/index.ts
import { installPhoton } from '@photonjs/runtime/vite'
import type { Plugin } from 'vite'
 
export interface FrameworkOptions {
  ssr?: boolean
  api?: boolean
  logging?: boolean
}
 
export function framework(options: FrameworkOptions = {}): Plugin[] {
  return installPhoton('my-framework', {
    fullInstall: true,
 
    resolveMiddlewares: () => {
      const middlewares = ['my-framework/core']
      if (options.logging) middlewares.push('my-framework/logging')
      return middlewares
    },
 
    entries: {
      ...(options.ssr && {
        ssr: { id: 'my-framework/ssr' }
      }),
 
      ...(options.api && {
        api: { id: 'my-framework/api' }
      })
    }
  })
}

User Integration

// vite.config.ts
import { framework } from 'my-framework/vite'
 
export default {
  plugins: [
    framework({
      ssr: true,
      api: true,
      logging: process.env.NODE_ENV === 'development'
    })
  ]
}