@photonjs/express

Express.js adapter for Photon, enabling universal web applications with the Express.js framework.

Overview

This adapter provides seamless integration between Photon and Express.js:
- Universal middleware support: Apply Photon middlewares to Express apps
- Multi-runtime deployment: Deploy to Node.js, edge runtimes, and more
- Hot Module Replacement: Full HMR support during development
- TypeScript support: Complete type safety with Express and Photon
- Production ready: Optimized for production deployments

Installation

``bash
npm install @photonjs/express express


or

pnpm add @photonjs/express express

or

yarn add @photonjs/express express
`

You'll also need the Express types for TypeScript:

`bash
npm install -D @types/express
`

Usage

$3

Create an Express server with Photon integration:

`ts
// src/server.ts
import express from 'express'
import { apply, serve } from '@photonjs/express'

const app = express()

// Your Express routes and middleware
app.get('/', (req, res) => {
res.send('Hello from Photon + Express!')
})

app.get('/api/users', (req, res) => {
res.json({ users: ['Alice', 'Bob'] })
})

// Apply Photon universal middlewares
apply(app)

// Start the server with Photon
export default serve(app)
`

$3

Configure Photon in your Vite config:

`ts
// vite.config.ts
import { photon } from '@photonjs/core/vite'

export default {
plugins: [
photon({
server: './src/server.ts'
})
]
}
`

$3

Apply framework-specific middlewares alongside Express middleware:

`ts
// src/server.ts
import express from 'express'
import { apply, serve } from '@photonjs/express'
import awesomeFramework from 'awesome-framework/universal-middleware'

const app = express()

// Express-specific middleware
app.use(express.json())
app.use(express.static('public'))

// Your routes
app.get('/', (req, res) => {
res.render('index', { title: 'My App' })
})

// Apply universal middlewares (includes framework middlewares)
apply(app, [
awesomeFramework,
// Additional universal middlewares...
])

export default serve(app)
`

API Reference

$3

#### apply(app, additionalMiddlewares?)

Applies Photon universal middlewares to an Express application.

Parameters:
- app: Express - The Express application instance
- additionalMiddlewares?: UniversalMiddleware[] - Optional additional middlewares

Returns: The same Express app instance (for chaining)

`ts
import { apply } from '@photonjs/express'

const app = express()
apply(app) // Applies configured universal middlewares
`

#### serve(app, options?)

Starts the Express server with Photon integration and HMR support.

Parameters:
- app: Express - The Express application instance
- options?: ServerOptions - Optional server configuration

Returns: The Express app instance

`ts
import { serve } from '@photonjs/express'

const app = express()
serve(app, {
port: 3000,
hostname: 'localhost'
})
`

$3

`ts
interface ServerOptions {
port?: number
hostname?: string
createServer?: typeof createServer
onCreate?: (server: Server) => void
}
`

$3

- ./apply - Middleware application utilities
- Development version: ./apply (dev mode)
- Production version: ./apply (production mode)
- ./serve - Server creation utilities
- Node.js version: ./serve (node runtime)
- Universal version: ./serve (other runtimes)

Development

$3

Start the development server with HMR:

`bash
npm run dev


or


pnpm dev
`

The server will automatically restart when you make changes to your code.

$3

Build your application for production:

`bash
npm run build


or


pnpm build
`

$3

Test your production build locally:

`bash
npm run preview


or


pnpm preview
`

Deployment

$3

The Express adapter is optimized for Node.js deployment:

`ts
// Your built server will work with standard Node.js hosting
node dist/server/index.js
`

$3

`dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist ./dist
EXPOSE 3000
CMD ["node", "dist/server/index.js"]
`

$3

The adapter works with various Node.js hosting platforms:
- Railway: Direct deployment with automatic port detection
- Render: Compatible with their Node.js runtime
- DigitalOcean App Platform: Works with their Node.js buildpack
- AWS Lambda: Use with serverless Express adapters
- Google Cloud Run: Deploy as containerized Node.js app

Advanced Usage

$3

You can customize the HTTP server creation:

`ts
import { createServer } from 'node:http'
import { serve } from '@photonjs/express'

const app = express()

serve(app, {
createServer: createServer,
onCreate: (server) => {
console.log('Server created:', server.address())
}
})
`

$3

Control the order of middleware application:

`ts
// Express middleware first
app.use(express.json())
app.use('/static', express.static('public'))

// Your routes
app.get('/api/*', apiRoutes)

// Apply Photon middlewares last
apply(app)
`

Examples

See the test applications for complete working examples.

Troubleshooting

$3

Port already in use:
`ts
serve(app, { port: process.env.PORT || 3001 })
``

Middleware order issues:
Apply Photon middlewares after your Express-specific middleware but before error handlers.

License

MIT