chore: progress

Author: harlan-zw

docs/content/docs/1.guides/2.bundling.md

@@ -244,18 +244,31 @@ $script.add({
 })
 ```
 
-### Change Asset Behavior
+### Asset Configuration
 
-Use the `assets` option in your configuration to customize how scripts are bundled, such as changing the output directory for the bundled scripts.
+Use the `assets` option in your configuration to customize how scripts are bundled and cached.
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
   scripts: {
     assets: {
       prefix: '/_custom-script-path/',
+      cacheMaxAge: 86400000, // 1 day in milliseconds
     }
   }
 })
 ```
 
-More configuration options will be available in future updates.
+#### Available Options
+
+- **`prefix`** - Custom path where bundled scripts are served (default: `/_scripts/`)
+- **`cacheMaxAge`** - Cache duration for bundled scripts in milliseconds (default: 7 days)
+
+#### Cache Behavior
+
+The bundling system uses two different cache strategies:
+
+- **Build-time cache**: Controlled by `cacheMaxAge` (default: 7 days). Scripts older than this are re-downloaded during builds to ensure freshness.
+- **Runtime cache**: Bundled scripts are served with 1-year cache headers since they are content-addressed by hash.
+
+This dual approach ensures both build performance and reliable browser caching.

src/module.ts

@@ -62,6 +62,12 @@ export interface ModuleOptions {
      * Configure the fetch options used for downloading scripts.
      */
     fetchOptions?: FetchOptions
+    /**
+     * Cache duration for bundled scripts in milliseconds.
+     * Scripts older than this will be re-downloaded during builds.
+     * @default 604800000 (7 days)
+     */
+    cacheMaxAge?: number
   }
   /**
    * Whether the module is enabled.
@@ -234,6 +240,7 @@ export {}`
         assetsBaseURL: config.assets?.prefix,
         fallbackOnSrcOnBundleFail: config.assets?.fallbackOnSrcOnBundleFail,
         fetchOptions: config.assets?.fetchOptions,
+        cacheMaxAge: config.assets?.cacheMaxAge,
         renderedScript,
       }))
 

src/plugins/transform.ts

@@ -20,13 +20,13 @@ import type { RegistryScript } from '#nuxt-scripts/types'
 
 const SEVEN_DAYS_IN_MS = 7 * 24 * 60 * 60 * 1000
 
-async function isCacheExpired(storage: any, filename: string): Promise<boolean> {
+async function isCacheExpired(storage: any, filename: string, cacheMaxAge: number = SEVEN_DAYS_IN_MS): Promise<boolean> {
   const metaKey = `bundle-meta:${filename}`
   const meta = await storage.getItem(metaKey)
   if (!meta || !meta.timestamp) {
     return true // No metadata means expired/invalid cache
   }
-  return Date.now() - meta.timestamp > SEVEN_DAYS_IN_MS
+  return Date.now() - meta.timestamp > cacheMaxAge
 }
 
 export interface AssetBundlerTransformerOptions {
@@ -36,6 +36,7 @@ export interface AssetBundlerTransformerOptions {
   scripts?: Required<RegistryScript>[]
   fallbackOnSrcOnBundleFail?: boolean
   fetchOptions?: FetchOptions
+  cacheMaxAge?: number
   renderedScript?: Map<string, {
     content: Buffer
     /**
@@ -68,7 +69,7 @@ async function downloadScript(opts: {
   url: string
   filename?: string
   forceDownload?: boolean
-}, renderedScript: NonNullable<AssetBundlerTransformerOptions['renderedScript']>, fetchOptions?: FetchOptions) {
+}, renderedScript: NonNullable<AssetBundlerTransformerOptions['renderedScript']>, fetchOptions?: FetchOptions, cacheMaxAge?: number) {
   const { src, url, filename, forceDownload } = opts
   if (src === url || !filename) {
     return
@@ -79,7 +80,7 @@ async function downloadScript(opts: {
   if (!res) {
     // Use storage to cache the font data between builds
     const cacheKey = `bundle:${filename}`
-    const shouldUseCache = !forceDownload && await storage.hasItem(cacheKey) && !(await isCacheExpired(storage, filename))
+    const shouldUseCache = !forceDownload && await storage.hasItem(cacheKey) && !(await isCacheExpired(storage, filename, cacheMaxAge))
 
     if (shouldUseCache) {
       const res = await storage.getItemRaw<Buffer>(cacheKey)
@@ -312,7 +313,7 @@ export function NuxtScriptBundleTransformer(options: AssetBundlerTransformerOpti
                     const { url: _url, filename } = normalizeScriptData(src, options.assetsBaseURL)
                     let url = _url
                     try {
-                      await downloadScript({ src, url, filename, forceDownload }, renderedScript, options.fetchOptions)
+                      await downloadScript({ src, url, filename, forceDownload }, renderedScript, options.fetchOptions, options.cacheMaxAge)
                     }
                     catch (e) {
                       if (options.fallbackOnSrcOnBundleFail) {

test/unit/transform.test.ts

@@ -497,6 +497,23 @@ const _sfc_main = /* @__PURE__ */ _defineComponent({
     `)
   })
 
+  it('custom cache max age is passed through', async () => {
+    vi.mocked(hash).mockImplementationOnce(() => 'beacon.min')
+    const customCacheMaxAge = 3600000 // 1 hour
+
+    const code = await transform(
+      `const instance = useScript('https://static.cloudflareinsights.com/beacon.min.js', {
+        bundle: true,
+      })`,
+      {
+        cacheMaxAge: customCacheMaxAge,
+      },
+    )
+
+    // Verify transformation still works with custom cache duration
+    expect(code).toMatchInlineSnapshot(`"const instance = useScript('/_scripts/beacon.min.js', )"`)
+  })
+
   describe.todo('fallbackOnSrcOnBundleFail', () => {
     beforeEach(() => {
       vi.mocked($fetch).mockImplementationOnce(() => Promise.reject(new Error('fetch error')))