qlara 0.1.2 → 0.1.3

package/dist/aws.cjs

@@ -520,14 +520,15 @@ async function bundleEdgeHandler(config) {
     define: {
       __QLARA_BUCKET_NAME__: JSON.stringify(config.bucketName),
       __QLARA_RENDERER_ARN__: JSON.stringify(config.rendererArn),
-      __QLARA_REGION__: JSON.stringify(config.region)
+      __QLARA_REGION__: JSON.stringify(config.region),
+      __QLARA_CACHE_TTL__: String(config.cacheTtl)
     },
     // Bundle everything — Lambda@Edge must be self-contained
     external: []
   });
   return createZip(outfile, "edge-handler.js");
 }
-async function bundleRenderer(routeFile) {
+async function bundleRenderer(routeFile, cacheTtl = 3600) {
   (0, import_node_fs2.mkdirSync)(BUNDLE_DIR, { recursive: true });
   const outfile = (0, import_node_path2.join)(BUNDLE_DIR, "renderer.js");
   const alias = {};
@@ -548,6 +549,9 @@ async function bundleRenderer(routeFile) {
     outfile,
     minify: true,
     alias,
+    define: {
+      __QLARA_CACHE_TTL__: String(cacheTtl)
+    },
     external: []
   });
   return createZip(outfile, "renderer.js");
@@ -764,6 +768,7 @@ function byoiResources(config) {
 function aws(awsConfig = {}) {
   const region = "us-east-1";
   const byoi = isByoi(awsConfig);
+  const cacheTtl = awsConfig.cacheTtl ?? 3600;
   const stackName = byoi ? "" : awsConfig.stackName || STACK_NAME_PREFIX;
   return {
     name: "aws",
@@ -845,7 +850,8 @@ function aws(awsConfig = {}) {
       const edgeZip = await bundleEdgeHandler({
         bucketName: res.bucketName,
         rendererArn: res.rendererFunctionArn,
-        region: res.region
+        region: res.region,
+        cacheTtl
       });
       const lambda = new import_client_lambda.LambdaClient({ region: res.region });
       console.log("[qlara/aws] Waiting for edge handler to be ready...");
@@ -922,7 +928,7 @@ function aws(awsConfig = {}) {
       const cf = new import_client_cloudfront.CloudFrontClient({ region: res.region });
       await updateCloudFrontEdgeVersion(cf, res.distributionId, newVersionArn);
       console.log("[qlara/aws] Bundling renderer...");
-      const rendererZip = await bundleRenderer(config.routeFile);
+      const rendererZip = await bundleRenderer(config.routeFile, cacheTtl);
       await (0, import_client_lambda.waitUntilFunctionUpdatedV2)(
         { client: lambda, maxWaitTime: 120 },
         { FunctionName: res.rendererFunctionArn }
@@ -997,6 +1003,21 @@ function aws(awsConfig = {}) {
           `[qlara/aws] Could not update renderer permissions: ${err.message}`
         );
       }
+      console.log("[qlara/aws] Warming up renderer...");
+      try {
+        await lambda.send(
+          new import_client_lambda.InvokeCommand({
+            FunctionName: res.rendererFunctionArn,
+            InvocationType: "RequestResponse",
+            Payload: JSON.stringify({ warmup: true })
+          })
+        );
+        console.log("[qlara/aws] Renderer warmed up");
+      } catch (err) {
+        console.warn(
+          `[qlara/aws] Renderer warm-up failed (non-critical): ${err.message}`
+        );
+      }
       console.log("[qlara/aws] Invalidating CloudFront cache...");
       await cf.send(
         new import_client_cloudfront.CreateInvalidationCommand({

package/dist/aws.d.cts

@@ -3,6 +3,16 @@ import { P as ProviderResources, Q as QlaraProvider } from './types-gl2xFqEX.cjs
 interface AwsConfig {
     stackName?: string;
     bucketName?: string;
+    /**
+     * How long (in seconds) CloudFront should cache dynamically rendered pages.
+     * This sets the `s-maxage` value on the Cache-Control header.
+     *
+     * - Browsers always revalidate with CloudFront (`max-age=0`)
+     * - CloudFront serves from edge cache for this duration
+     *
+     * @default 3600 (1 hour)
+     */
+    cacheTtl?: number;
     distributionId?: string;
     distributionDomain?: string;
     edgeFunctionArn?: string;

package/dist/aws.d.ts

@@ -3,6 +3,16 @@ import { P as ProviderResources, Q as QlaraProvider } from './types-gl2xFqEX.js'
 interface AwsConfig {
     stackName?: string;
     bucketName?: string;
+    /**
+     * How long (in seconds) CloudFront should cache dynamically rendered pages.
+     * This sets the `s-maxage` value on the Cache-Control header.
+     *
+     * - Browsers always revalidate with CloudFront (`max-age=0`)
+     * - CloudFront serves from edge cache for this duration
+     *
+     * @default 3600 (1 hour)
+     */
+    cacheTtl?: number;
     distributionId?: string;
     distributionDomain?: string;
     edgeFunctionArn?: string;

package/dist/aws.js

@@ -15,6 +15,7 @@ import {
   UpdateFunctionConfigurationCommand,
   PublishVersionCommand,
   AddPermissionCommand,
+  InvokeCommand,
   waitUntilFunctionUpdatedV2
 } from "@aws-sdk/client-lambda";
 import {
@@ -515,14 +516,15 @@ async function bundleEdgeHandler(config) {
     define: {
       __QLARA_BUCKET_NAME__: JSON.stringify(config.bucketName),
       __QLARA_RENDERER_ARN__: JSON.stringify(config.rendererArn),
-      __QLARA_REGION__: JSON.stringify(config.region)
+      __QLARA_REGION__: JSON.stringify(config.region),
+      __QLARA_CACHE_TTL__: String(config.cacheTtl)
     },
     // Bundle everything — Lambda@Edge must be self-contained
     external: []
   });
   return createZip(outfile, "edge-handler.js");
 }
-async function bundleRenderer(routeFile) {
+async function bundleRenderer(routeFile, cacheTtl = 3600) {
   mkdirSync(BUNDLE_DIR, { recursive: true });
   const outfile = join2(BUNDLE_DIR, "renderer.js");
   const alias = {};
@@ -543,6 +545,9 @@ async function bundleRenderer(routeFile) {
     outfile,
     minify: true,
     alias,
+    define: {
+      __QLARA_CACHE_TTL__: String(cacheTtl)
+    },
     external: []
   });
   return createZip(outfile, "renderer.js");
@@ -759,6 +764,7 @@ function byoiResources(config) {
 function aws(awsConfig = {}) {
   const region = "us-east-1";
   const byoi = isByoi(awsConfig);
+  const cacheTtl = awsConfig.cacheTtl ?? 3600;
   const stackName = byoi ? "" : awsConfig.stackName || STACK_NAME_PREFIX;
   return {
     name: "aws",
@@ -840,7 +846,8 @@ function aws(awsConfig = {}) {
       const edgeZip = await bundleEdgeHandler({
         bucketName: res.bucketName,
         rendererArn: res.rendererFunctionArn,
-        region: res.region
+        region: res.region,
+        cacheTtl
       });
       const lambda = new LambdaClient({ region: res.region });
       console.log("[qlara/aws] Waiting for edge handler to be ready...");
@@ -917,7 +924,7 @@ function aws(awsConfig = {}) {
       const cf = new CloudFrontClient({ region: res.region });
       await updateCloudFrontEdgeVersion(cf, res.distributionId, newVersionArn);
       console.log("[qlara/aws] Bundling renderer...");
-      const rendererZip = await bundleRenderer(config.routeFile);
+      const rendererZip = await bundleRenderer(config.routeFile, cacheTtl);
       await waitUntilFunctionUpdatedV2(
         { client: lambda, maxWaitTime: 120 },
         { FunctionName: res.rendererFunctionArn }
@@ -992,6 +999,21 @@ function aws(awsConfig = {}) {
           `[qlara/aws] Could not update renderer permissions: ${err.message}`
         );
       }
+      console.log("[qlara/aws] Warming up renderer...");
+      try {
+        await lambda.send(
+          new InvokeCommand({
+            FunctionName: res.rendererFunctionArn,
+            InvocationType: "RequestResponse",
+            Payload: JSON.stringify({ warmup: true })
+          })
+        );
+        console.log("[qlara/aws] Renderer warmed up");
+      } catch (err) {
+        console.warn(
+          `[qlara/aws] Renderer warm-up failed (non-critical): ${err.message}`
+        );
+      }
       console.log("[qlara/aws] Invalidating CloudFront cache...");
       await cf.send(
         new CreateInvalidationCommand({

package/dist/cli.js

@@ -26,6 +26,7 @@ import {
   UpdateFunctionConfigurationCommand,
   PublishVersionCommand,
   AddPermissionCommand,
+  InvokeCommand,
   waitUntilFunctionUpdatedV2
 } from "@aws-sdk/client-lambda";
 import {
@@ -526,14 +527,15 @@ async function bundleEdgeHandler(config) {
     define: {
       __QLARA_BUCKET_NAME__: JSON.stringify(config.bucketName),
       __QLARA_RENDERER_ARN__: JSON.stringify(config.rendererArn),
-      __QLARA_REGION__: JSON.stringify(config.region)
+      __QLARA_REGION__: JSON.stringify(config.region),
+      __QLARA_CACHE_TTL__: String(config.cacheTtl)
     },
     // Bundle everything — Lambda@Edge must be self-contained
     external: []
   });
   return createZip(outfile, "edge-handler.js");
 }
-async function bundleRenderer(routeFile) {
+async function bundleRenderer(routeFile, cacheTtl = 3600) {
   mkdirSync(BUNDLE_DIR, { recursive: true });
   const outfile = join2(BUNDLE_DIR, "renderer.js");
   const alias = {};
@@ -554,6 +556,9 @@ async function bundleRenderer(routeFile) {
     outfile,
     minify: true,
     alias,
+    define: {
+      __QLARA_CACHE_TTL__: String(cacheTtl)
+    },
     external: []
   });
   return createZip(outfile, "renderer.js");
@@ -767,6 +772,7 @@ function byoiResources(config) {
 function aws(awsConfig = {}) {
   const region = "us-east-1";
   const byoi = isByoi(awsConfig);
+  const cacheTtl = awsConfig.cacheTtl ?? 3600;
   const stackName = byoi ? "" : awsConfig.stackName || STACK_NAME_PREFIX;
   return {
     name: "aws",
@@ -848,7 +854,8 @@ function aws(awsConfig = {}) {
       const edgeZip = await bundleEdgeHandler({
         bucketName: res.bucketName,
         rendererArn: res.rendererFunctionArn,
-        region: res.region
+        region: res.region,
+        cacheTtl
       });
       const lambda = new LambdaClient({ region: res.region });
       console.log("[qlara/aws] Waiting for edge handler to be ready...");
@@ -925,7 +932,7 @@ function aws(awsConfig = {}) {
       const cf = new CloudFrontClient({ region: res.region });
       await updateCloudFrontEdgeVersion(cf, res.distributionId, newVersionArn);
       console.log("[qlara/aws] Bundling renderer...");
-      const rendererZip = await bundleRenderer(config.routeFile);
+      const rendererZip = await bundleRenderer(config.routeFile, cacheTtl);
       await waitUntilFunctionUpdatedV2(
         { client: lambda, maxWaitTime: 120 },
         { FunctionName: res.rendererFunctionArn }
@@ -1000,6 +1007,21 @@ function aws(awsConfig = {}) {
           `[qlara/aws] Could not update renderer permissions: ${err.message}`
         );
       }
+      console.log("[qlara/aws] Warming up renderer...");
+      try {
+        await lambda.send(
+          new InvokeCommand({
+            FunctionName: res.rendererFunctionArn,
+            InvocationType: "RequestResponse",
+            Payload: JSON.stringify({ warmup: true })
+          })
+        );
+        console.log("[qlara/aws] Renderer warmed up");
+      } catch (err) {
+        console.warn(
+          `[qlara/aws] Renderer warm-up failed (non-critical): ${err.message}`
+        );
+      }
       console.log("[qlara/aws] Invalidating CloudFront cache...");
       await cf.send(
         new CreateInvalidationCommand({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qlara",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Runtime ISR for static React apps — dynamic routing and SEO metadata for statically exported Next.js apps on AWS",
   "license": "MIT",
   "keywords": [

package/src/provider/aws/edge-handler.ts

@@ -24,6 +24,7 @@ import { LambdaClient, InvokeCommand } from '@aws-sdk/client-lambda';
 declare const __QLARA_BUCKET_NAME__: string;
 declare const __QLARA_RENDERER_ARN__: string;
 declare const __QLARA_REGION__: string;
+declare const __QLARA_CACHE_TTL__: number;
 // ── Types (inlined to keep bundle self-contained) ────────────────
 
 interface ManifestRoute {
@@ -238,7 +239,7 @@ function buildHtmlResponse(
       { key: 'Content-Type', value: 'text/html; charset=utf-8' },
     ],
     'cache-control': [
-      { key: 'Cache-Control', value: 'public, max-age=0, must-revalidate' },
+      { key: 'Cache-Control', value: `public, max-age=0, s-maxage=${__QLARA_CACHE_TTL__}, stale-while-revalidate=60` },
     ],
   };
 

package/src/provider/aws/renderer.ts

@@ -52,6 +52,9 @@ import type {
 // The routes module is resolved by esbuild at deploy time.
 // esbuild's `alias` option maps this import to the developer's route file.
 // At bundle time: '__qlara_routes__' → './qlara.routes.ts' (or wherever the dev put it)
+// Injected at bundle time by esbuild define
+declare const __QLARA_CACHE_TTL__: number;
+
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-ignore — resolved at bundle time by esbuild alias
 import routes from '__qlara_routes__';
@@ -752,20 +755,30 @@ function metadataToRscEntries(metadata: QlaraMetadata): string {
   return entries.join('');
 }
 
-export async function handler(event: RendererEvent): Promise<RendererResult> {
+export async function handler(event: RendererEvent & { warmup?: boolean }): Promise<RendererResult> {
+  // Warmup invocation — just initialize the runtime and return
+  if (event.warmup) {
+    return { statusCode: 200, body: 'warm' };
+  }
+
   const { uri, bucket, routePattern, params } = event;
   const region = process.env.AWS_REGION || 'us-east-1';
 
   const s3 = new S3Client({ region });
 
   try {
-    // 0. Check if the page was already rendered (guards against duplicate concurrent requests)
+    // 0. Check if already rendered + read fallback in parallel
     const s3Key = deriveS3Key(uri);
-    try {
-      const existing = await s3.send(
-        new GetObjectCommand({ Bucket: bucket, Key: s3Key })
-      );
-      const existingHtml = await existing.Body?.transformToString('utf-8');
+    const fallbackKey = deriveFallbackKey(uri);
+
+    const [existingResult, fallbackResult] = await Promise.allSettled([
+      s3.send(new GetObjectCommand({ Bucket: bucket, Key: s3Key })),
+      s3.send(new GetObjectCommand({ Bucket: bucket, Key: fallbackKey })),
+    ]);
+
+    // If page already exists, return it (guards against duplicate concurrent requests)
+    if (existingResult.status === 'fulfilled') {
+      const existingHtml = await existingResult.value.Body?.transformToString('utf-8');
       if (existingHtml) {
         return {
           statusCode: 200,
@@ -773,26 +786,20 @@ export async function handler(event: RendererEvent): Promise<RendererResult> {
           html: existingHtml,
         };
       }
-    } catch {
-      // Page doesn't exist yet — continue with rendering
     }
 
-    // 1. Read the fallback HTML from S3
-    const fallbackKey = deriveFallbackKey(uri);
+    // Extract fallback HTML
     let fallbackHtml: string;
 
-    try {
-      const response = await s3.send(
-        new GetObjectCommand({ Bucket: bucket, Key: fallbackKey })
-      );
-      fallbackHtml = (await response.Body?.transformToString('utf-8')) || '';
+    if (fallbackResult.status === 'fulfilled') {
+      fallbackHtml = (await fallbackResult.value.Body?.transformToString('utf-8')) || '';
       if (!fallbackHtml) {
         return {
           statusCode: 500,
           body: JSON.stringify({ error: `Empty fallback at ${fallbackKey}` }),
         };
       }
-    } catch {
+    } else {
       return {
         statusCode: 500,
         body: JSON.stringify({ error: `Fallback not found: ${fallbackKey}` }),
@@ -824,8 +831,7 @@ export async function handler(event: RendererEvent): Promise<RendererResult> {
         Key: s3Key,
         Body: html,
         ContentType: 'text/html; charset=utf-8',
-        CacheControl:
-          'public, max-age=0, s-maxage=31536000, stale-while-revalidate=86400',
+        CacheControl: `public, max-age=0, s-maxage=${__QLARA_CACHE_TTL__}, stale-while-revalidate=60`,
       })
     );