Docs Menu
API
Get Started
Edit this page

@photonjs/core

@photonjs/core

v0.0.7
Alpha

The core package provides the foundation of Photon with Vite integration and core functionality.

npm install @photonjs/core

Exports

./vite

Vite plugin for Photon integration.

import { photon } from '@photonjs/core/vite'
 
export default {
  plugins: [photon(config)]
}

./api

TODO

Core API functions for managing entries and configuration.

import { addPhotonEntry, updatePhotonEntry, getPhotonServerIdWithEntry } from '@photonjs/core/api'
 
// Add a new entry
addPhotonEntry(entry)
 
// Update an existing entry
updatePhotonEntry(id, updates)
 
// Get server ID with entry
getPhotonServerIdWithEntry(entryId)

./errors

Error classes for Photon-specific errors.

import {
  PhotonError,
  PhotonConfigError,
  PhotonRuntimeError,
  PhotonUsageError,
  PhotonDependencyError,
  PhotonBugError
} from '@photonjs/core/errors'

Functions

photon(config?)

Creates the Photon Vite plugin.

function photon(config?: Photon.Config): Plugin[]

Parameters:

  • config - Optional Photon configuration

Returns: Array of Vite plugins

Example:

import { photon } from '@photonjs/core/vite'
 
export default {
  plugins: [
    photon({
      server: './src/server.ts',
      entries: {
        'api/users': './src/api/users.ts'
      }
    })
  ]
}

Configuration

Photon.Config

Main configuration interface.

interface Config {
  server?: string | EntryServerPartial
  entries?: Record<string, string | EntryPartial>
}

Properties:

  • server - Server entry point or configuration
  • entries - Additional entries (API routes, middleware, etc.)

Photon.EntryServer

Server entry configuration.

interface EntryServer {
  id: string
  name: string
  type: 'server'
  server: SupportedServers
  file: string
}

Photon.EntryPartial

Partial entry configuration for additional entries.

interface EntryPartial {
  type?: 'universal-handler'
  file?: string
}

Virtual Modules

Photon provides virtual modules resolved at build time:

photon:get-middlewares:*

Access to universal middlewares for different runtimes.

declare module 'photon:get-middlewares:dev:hono' {
  export const getUniversalEntries: () => UniversalHandler[]
  export const getUniversalMiddlewares: () => UniversalMiddleware[]
}

photon:server-entry

The main server entry point.

declare module 'photon:server-entry' {
  const handler: any
  export default handler
}

Error Classes

PhotonError

Base error class for all Photon errors.

class PhotonError extends Error {
  constructor(message: string)
}

PhotonConfigError

Configuration-related errors.

class PhotonConfigError extends PhotonError {
  constructor(message: string)
}

PhotonRuntimeError

Runtime execution errors.

class PhotonRuntimeError extends PhotonError {
  constructor(message: string)
}

PhotonUsageError

API usage errors.

class PhotonUsageError extends PhotonError {
  constructor(message: string)
}

API Functions

addPhotonEntry(entry)

Add a new Photon entry.

function addPhotonEntry(entry: Photon.Entry): void

updatePhotonEntry(id, updates)

Update an existing entry.

function updatePhotonEntry(
  id: string, 
  updates: Partial<Photon.Entry>
): void

getPhotonServerIdWithEntry(entryId)

Get server ID associated with an entry.

function getPhotonServerIdWithEntry(entryId: string): string | null

Type Utilities

Photon Namespace

All Photon types are available under the Photon namespace:

import type { Photon } from '@photonjs/core'
 
type Config = Photon.Config
type Entry = Photon.Entry
type EntryServer = Photon.EntryServer

Examples

Basic Setup

// vite.config.ts
import { photon } from '@photonjs/core/vite'
 
export default {
  plugins: [
    photon({
      server: './src/server.ts'
    })
  ]
}

Advanced Configuration

// vite.config.ts
import { photon } from '@photonjs/core/vite'
 
export default {
  plugins: [
    photon({
      server: {
        file: './src/server.ts',
        server: 'hono'
      },
      entries: {
        'api/users': './src/api/users.ts',
        'api/posts': './src/api/posts.ts',
        'middleware/auth': {
          file: './src/middleware/auth.ts',
          type: 'universal-handler'
        }
      }
    })
  ]
}

Error Handling

import { PhotonConfigError } from '@photonjs/core/errors'
 
try {
  // Photon operations
} catch (error) {
  if (error instanceof PhotonConfigError) {
    console.error('Configuration error:', error.message)
  }
}