# Middleware configuration This guide provides detailed examples and configuration options for setting up Aurelia SSR middleware with various server frameworks and scenarios. ## Basic Koa Middleware Setup The most common setup uses Koa with `aurelia-middleware-koa`: ```javascript const Koa = require('koa'); const render = require('aurelia-middleware-koa'); const path = require('path'); const fs = require('fs'); const app = new Koa(); // Load HTML template const indexTemplate = fs.readFileSync( path.join(__dirname, '../index.html'), 'utf-8' ); // Basic SSR middleware configuration app.use(render({ main: path.join(__dirname, '../dist-server/server.js'), template: indexTemplate })); app.listen(3000); ``` ## Advanced Configuration Options ### Complete Configuration Object ```javascript app.use(render({ // Required: Path to your server bundle main: path.join(__dirname, '../dist-server/server.js'), // Required: HTML template template: indexTemplate, // Optional: Custom template insertion logic insertInto: (template, rendered) => { return template.replace('', rendered); }, // Optional: Error handling onError: (error, request) => { console.error('SSR Error:', error); return '
Error loading page
'; }, // Optional: Request preprocessing beforeRender: (request) => { // Modify request before rendering console.log(`Rendering: ${request.url}`); return request; }, // Optional: Response post-processing afterRender: (html, request) => { // Modify rendered HTML return html.replace('{{timestamp}}', new Date().toISOString()); }, // Optional: Skip SSR for certain routes skipRoutes: ['/api', '/admin'], // Optional: Cache configuration cache: { enabled: process.env.NODE_ENV === 'production', ttl: 60000, // 1 minute cache key: (request) => request.url } })); ``` ## Environment-Specific Configuration ### Development Configuration ```javascript const isDevelopment = process.env.NODE_ENV === 'development'; app.use(render({ main: path.join(__dirname, '../dist-server/server.js'), template: indexTemplate, // Enable detailed error reporting in development onError: isDevelopment ? (error, request) => { console.error('SSR Error:', error.stack); return `

SSR Error (Development Only)

${error.stack}

URL: ${request.url}

`; } : (error, request) => { console.error('SSR Error:', error.message); return '
Page temporarily unavailable
'; }, // Disable caching in development cache: { enabled: false } })); ``` ### Production Configuration ```javascript const isProduction = process.env.NODE_ENV === 'production'; if (isProduction) { app.use(render({ main: path.join(__dirname, '../dist-server/server.js'), template: indexTemplate, // Graceful error handling onError: (error, request) => { // Log error for monitoring console.error(`SSR Error [${new Date().toISOString()}]:`, { message: error.message, url: request.url, userAgent: request.headers['user-agent'] }); // Return fallback content return `

Welcome

Please enable JavaScript to view this application.

`; }, // Enable production caching cache: { enabled: true, ttl: 5 * 60 * 1000, // 5 minutes key: (request) => { // Create cache key based on URL and user agent return `${request.url}-${request.headers['user-agent']}`; } } })); } ``` ## Custom Template Insertion ### Multiple Insertion Points ```javascript const template = ` <!--title-placeholder-->
`; app.use(render({ main: path.join(__dirname, '../dist-server/server.js'), template: template, insertInto: (template, rendered, request, initialState) => { return template .replace('', initialState.title || 'Default Title') .replace('', initialState.description || 'Default description') .replace('', rendered) .replace('', JSON.stringify(initialState)); } })); ``` ### Dynamic Meta Tags ```javascript app.use(render({ main: path.join(__dirname, '../dist-server/server.js'), template: indexTemplate, insertInto: (template, rendered, request, state) => { // Generate meta tags based on rendered content const metaTags = generateMetaTags(state, request); const htmlWithMeta = template.replace( '', `${metaTags}` ); return htmlWithMeta.replace('', rendered); } })); function generateMetaTags(state, request) { const meta = []; if (state.pageTitle) { meta.push(`${state.pageTitle}`); } if (state.pageDescription) { meta.push(``); } // Open Graph tags if (state.ogImage) { meta.push(``); } return meta.join('\n'); } ``` ## Request Preprocessing ### Authentication Handling ```javascript app.use(render({ main: path.join(__dirname, '../dist-server/server.js'), template: indexTemplate, beforeRender: (request) => { // Extract authentication information const authToken = request.headers.authorization; const userId = extractUserIdFromToken(authToken); // Add user context to request request.userContext = { isAuthenticated: !!userId, userId: userId, permissions: getUserPermissions(userId) }; return request; } })); function extractUserIdFromToken(authToken) { // Implement your JWT/token parsing logic try { const token = authToken?.replace('Bearer ', ''); // Parse and validate token return parseJWT(token)?.userId; } catch (error) { return null; } } ``` ### Internationalization ```javascript app.use(render({ main: path.join(__dirname, '../dist-server/server.js'), template: indexTemplate, beforeRender: (request) => { // Determine user's language preference const acceptLanguage = request.headers['accept-language']; const userLang = parseLanguageHeader(acceptLanguage); // Add language context request.i18nContext = { locale: userLang, fallbackLocale: 'en', translations: loadTranslations(userLang) }; return request; } })); function parseLanguageHeader(acceptLanguage) { // Parse Accept-Language header const languages = acceptLanguage?.split(',').map(lang => { const [code, priority = '1'] = lang.trim().split(';q='); return { code: code.split('-')[0], priority: parseFloat(priority) }; }).sort((a, b) => b.priority - a.priority); return languages?.[0]?.code || 'en'; } ``` ## Response Post-processing ### Performance Monitoring ```javascript app.use(render({ main: path.join(__dirname, '../dist-server/server.js'), template: indexTemplate, afterRender: (html, request, renderTime) => { // Add performance metrics const perfScript = ` `; return html.replace('', `${perfScript}`); } })); ``` ### Content Security Policy ```javascript app.use(render({ main: path.join(__dirname, '../dist-server/server.js'), template: indexTemplate, afterRender: (html, request) => { // Generate nonce for inline scripts const nonce = generateNonce(); // Add CSP header request.ctx.set('Content-Security-Policy', `default-src 'self'; script-src 'self' 'nonce-${nonce}'; style-src 'self' 'unsafe-inline';` ); // Update inline scripts with nonce return html.replace( / `; } ``` ## Integration with Other Middleware ### Combining with Static File Serving ```javascript const Koa = require('koa'); const serve = require('koa-static'); const render = require('aurelia-middleware-koa'); const app = new Koa(); // Serve static files first app.use(serve(path.join(__dirname, '../dist'), { maxAge: 86400000, // 1 day cache for static files gzip: true })); // Then SSR for remaining routes app.use(render({ main: path.join(__dirname, '../dist-server/server.js'), template: indexTemplate })); app.listen(3000); ``` ### With Authentication Middleware ```javascript const session = require('koa-session'); const passport = require('koa-passport'); // Session middleware app.use(session(app)); app.use(passport.initialize()); app.use(passport.session()); // Authentication middleware app.use(async (ctx, next) => { if (ctx.isAuthenticated()) { ctx.state.user = ctx.state.user || {}; ctx.state.user.isAuthenticated = true; } await next(); }); // SSR middleware with user context app.use(render({ main: path.join(__dirname, '../dist-server/server.js'), template: indexTemplate, beforeRender: (request) => { // Pass user authentication state to SSR request.authState = { isAuthenticated: request.ctx.isAuthenticated(), user: request.ctx.state.user }; return request; } })); ``` This comprehensive middleware configuration guide should help you set up SSR for various scenarios and requirements. Remember to test your configuration thoroughly in both development and production environments.