nuxt-content-assets 1.4.1 → 1.4.3

package/README.md

@@ -8,7 +8,7 @@
 > Enable locally-located assets in Nuxt Content
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/davestewart/nuxt-content-assets/main/playground/content/splash.png" alt="Nuxt Content Assets logo">
+  <img src="https://raw.githubusercontent.com/davestewart/nuxt-content-assets/main/playground/public/splash.png" alt="Nuxt Content Assets logo">
 </p>
 
 ## Overview
@@ -155,11 +155,16 @@ If you delete an asset, it will be greyed out in the browser until you replace t
 
 If you edit an image, video, embed or iframe source, the content will update immediately, which is useful if you're looking to get that design just right!
 
+> [!NOTE]
+> Live reload does not currently work with Nuxt Image (see Issue [#77](https://github.com/davestewart/nuxt-content-assets/issues/77)).
+> 
+> If you need to iterate on image design, consider disabling Nuxt Image in development.
+
 ### Image sizing
 
 #### HTML
 
-The module is [preconfigured](#image-size) to pass image size hints (by default `style`) to generated `<img>` tags:
+The module can pass image size hints to generated `<img>` tags:
 
 ```html
 <!-- imageSize: 'style' -->
@@ -169,7 +174,10 @@ The module is [preconfigured](#image-size) to pass image size hints (by default
 <img src="/image.jpg" width="640" height="480">
 ```
 
-Keeping this on prevents content jumps as your page loads.
+Turning this on prevents content jumps as your page loads.
+
+> [!CAUTION]
+> Don't use `imageSize: 'src'` in conjunction with Nuxt Image as it prevents the IPX module from correctly serving images, which causes static site generation to fail 
 
 #### Prose components
 
@@ -207,27 +215,17 @@ See playground component [here](playground/components/content/ContentImage.vue).
 
 ### Nuxt Image
 
-Nuxt Content Assets works with [Nuxt Image](https://image.nuxtjs.org/) with just a little configuration:
+[Nuxt Image](https://image.nuxtjs.org/) is supported by adding Nuxt Content Asset's cache folder as a Nuxt Layer:
 
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
-  modules: [
-    // Nuxt Image should be placed before Nuxt Content Assets
-    '@nuxt/image',
-    'nuxt-content-assets',
-    '@nuxt/content',
-  ],
-
   extends: [
-    // add Nuxt Content Assets build folder as a Nuxt Layer (since v1.4.0)
-    '.nuxt/content-assets',
+    'node_modules/nuxt-content-assets/cache',
   ],
 }
 ```
 
-> Note that the new Layers setup enables Nuxt Image to load images from both the project's `public` folder and from `content`.
-
 To serve all images as Nuxt Image images, create a `ProseImg` component like so:
 
 ```vue
@@ -239,7 +237,6 @@ To serve all images as Nuxt Image images, create a `ProseImg` component like so:
 
 See the playground folder for both the [global](playground/components/temp/ProseImg.vue) and a [per image](playground/components/content/NuxtImg.ts) solution.
 
-
 ## Configuration
 
 The module has the following options:
@@ -248,7 +245,7 @@ The module has the following options:
 // nuxt.config.ts
 export default defineNuxtConfig({
   contentAssets: {    
-    // inject image sizes into the rendered html
+    // inject image size hints into the rendered html
     imageSize: 'style',
     
     // treat these extensions as content
@@ -262,7 +259,7 @@ export default defineNuxtConfig({
 
 ### Image size
 
-You can add one or more image size hints to the generated images:
+You can add one _or more_ image size hints to the generated images:
 
 ```ts
 {
@@ -277,7 +274,6 @@ Pick from the following switches:
 | `'style'` | Adds `style="aspect-ratio:..."` to any `<img>` tag                 |
 | `'attrs'` | Adds `width` and `height` attributes to any `<img>` tag            |
 | `'src'`   | Adds `?width=...&height=...` to `src` attribute (frontmatter only) |
-| `false`   | Disable image size hints                                           |
 
 Note: if you add *only* `attrs`, include the following CSS in your app:
 
@@ -288,8 +284,13 @@ img {
 }
 ```
 
+> [!Note]
+> 
+> Since `v1.4.1` image size hints are now opt-in. This was done to maximise compatibiility with Nuxt Image.  
+
 ### Content extensions
 
+> [!NOTE]
 > Generally, you shouldn't need to touch this setting
 
 This setting tells Nuxt Content to ignore anything that is **not** one of these file extensions:
@@ -312,65 +313,85 @@ If you want to see what the module does as it runs, set `debug` to true:
 
 ## How it works
 
-When Nuxt builds, the module scans all content sources for assets, copies them to an accessible public assets folder, and indexes path and image metadata.
+When Nuxt builds, the module scans all content sources for assets, copies them to a temporary layer folder (`nuxt_modules/nuxt-content-assets/cache`), and indexes path and image metadata.
 
-After Nuxt Content has run, the parsed content is traversed, and both element attributes and frontmatter properties are checked to see if they resolve to the indexed asset paths.
+After Nuxt Content has run, the parsed content (`.nuxt/content-cache`) is traversed, and both element attributes and frontmatter properties are checked to see if they resolve to the previously-indexed asset paths.
 
-If they do, then the attribute or property is rewritten with the absolute path. If the asset is an image, then the element or metadata is optionally updated with size attributes or a query string.
+If they do, then the attribute or property in Nuxt Content's cache is rewritten with the absolute path. If the asset is an image, then the element or metadata is optionally updated with size attributes or a query string.
 
 Finally, Nitro serves the site, and any requests made to the transformed asset paths should be picked up and the *copied* asset served by the browser.
 
-In development, file watching propagates asset changes to the public folder, updates related cached content, and notifies the browser via web sockets to refresh any loaded images. 
+In development, a watch process propagates asset changes to the cache, updates the asset index, and notifies the browser via web sockets to refresh any loaded images. 
+
+If Nuxt Image is used, the `_ipx/` endpoint serves images directly from the cache's public folder.
 
 ## Development
 
-Should you wish to develop the project, the scripts are:
+Should you wish to develop the project, you'll work with the following entities:
+
+- [src](./src)<br>The module code itself
+- [playground](./playground)<br>A standalone Nuxt app that reads the live module code
+- [scripts](package.json)<br>A set of scripts to develop and publish the module
+
+### Setup
 
-Develop the module (running the playground which uses the live module code):
+To set up the project, run each of these scripts once:
 
 ```bash
 # install dependencies
 npm install
 
-# generate playground type stubs (for the first time)
-npm run dev:prepare
+# copy the cache folder to the playground's node_modules (workaround required in development)
+npm run dev:setup
 
-# develop (runs the playground app)
-npm run dev
-
-# run eslint
-npm run lint
-
-# run vitest
-npm run test
-npm run test:watch
+# generate types for the module and playground (re-run if you install new packages)
+npm run dev:prepare
 ```
 
-Build and check the playground (simulating users' final build choices):
+### Development
+
+To develop the module, utilise the supplied playground app:
 
 ```bash
+# compile the module, run and serve the playground
+npm run dev
+
 # generate the playground
 npm run dev:generate
 
 # build the playground
 npm run dev:build
 
-# serve the generated / built playground
+# serve the generated/built playground
 npm run dev:preview
 ```
 
-Make a new release (so users can install the module):
+Check your code quality using these tools:
 
 ```bash
-# dry run the release
+# lint your code with eslint
+npm run lint
+
+# runs tests with vitest
+npm run test
+npm run test:watch
+```
+
+### Publishing
+
+> [!IMPORTANT]
+> Before publishing, be sure to update the [version](package.json) and [changelog](CHANGELOG.md)!
+
+To build and publish, run following scripts as required:
+
+```bash
+# lint, test, build, and dry-run publish
 npm run release:dry
 
-# release new version
+# lint, test, build and publish
 npm run release
 ```
 
-Make sure to edit changelog and update `package.json` version before releasing!
-
 ## Maintenance
 
 This module was created using the Nuxt [Module Builder](https://github.com/nuxt/module-builder) command:
@@ -385,6 +406,8 @@ This created the module code from the starter template found here:
 
 Both [Nuxi](https://github.com/nuxt/cli) and the module's dependencies and scripts are updated fairly regularly, so from time to time this module may need to be updated to keep in sync. So far, this has meant just updating the dependencies and scripts, which are found in the starter template code mentioned above.
 
+Note that the build/release scripts are slightly modified from the originals; build is now separated, and release now doesn't use [changelogen](https://github.com/unjs/changelogen), or automatically add tags and push to GitHub.
+
 <!-- Badges -->
 [npm-version-src]: https://img.shields.io/npm/v/nuxt-content-assets/latest.svg?style=flat&colorA=18181B&colorB=28CF8D
 [npm-version-href]: https://npmjs.com/package/nuxt-content-assets

package/cache/nuxt.config.ts

@@ -0,0 +1 @@
+export default {}

package/cache/public/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

package/dist/module.json

@@ -4,5 +4,5 @@
   "compatibility": {
     "nuxt": "^3.0.0"
   },
-  "version": "1.4.0"
+  "version": "1.4.3"
 }

package/dist/module.mjs

@@ -1,4 +1,5 @@
-import Fs from 'fs';
+import * as Fs from 'fs';
+import Fs__default from 'fs';
 import Path from 'crosspath';
 import { useNuxt, createResolver, defineNuxtModule, addPlugin } from '@nuxt/kit';
 import { visit, SKIP, CONTINUE } from 'unist-util-visit';
@@ -153,35 +154,47 @@ function buildQuery(...expr) {
 }
 
 function readFile(path, asJson = false) {
-  const text = Fs.readFileSync(path, { encoding: "utf8" });
+  const text = Fs__default.readFileSync(path, { encoding: "utf8" });
   return asJson ? JSON.parse(text) : text;
 }
 function writeFile(path, data) {
   const text = typeof data === "object" ? JSON.stringify(data, null, "  ") : String(data);
   createFolder(Path.dirname(path));
-  Fs.writeFileSync(path, text, { encoding: "utf8" });
+  Fs__default.writeFileSync(path, text, { encoding: "utf8" });
 }
 async function writeBlob(path, data) {
   const buffer = Buffer.from(await data.arrayBuffer());
   createFolder(Path.dirname(path));
-  Fs.writeFileSync(path, buffer);
+  Fs__default.writeFileSync(path, buffer);
 }
 function copyFile(src, trg) {
   createFolder(Path.dirname(trg));
-  Fs.copyFileSync(src, trg);
+  Fs__default.copyFileSync(src, trg);
 }
 function removeFile(src) {
-  Fs.rmSync(src);
+  Fs__default.rmSync(src);
 }
 function createFolder(path) {
-  Fs.mkdirSync(path, { recursive: true });
+  Fs__default.mkdirSync(path, { recursive: true });
 }
 function removeFolder(path) {
   const isDownstream = path.startsWith(Path.resolve());
   if (isDownstream) {
-    Fs.rmSync(path, { recursive: true, force: true });
+    Fs__default.rmSync(path, { recursive: true, force: true });
   }
 }
+function removeEntry(path) {
+  if (Fs__default.existsSync(path)) {
+    if (isFile(path)) {
+      removeFile(path);
+    } else {
+      removeFolder(path);
+    }
+  }
+}
+function isFile(path) {
+  return Fs__default.lstatSync(path).isFile();
+}
 
 function createWebSocket() {
   const wss = new WebSocketServer({ noServer: true });
@@ -390,22 +403,23 @@ function makeSourceManager(key, source, publicPath, callback) {
 }
 
 function makeAssetsManager(publicPath, shouldWatch = true) {
-  const indexKey = "assets.json";
-  const storage = makeSourceStorage(Path.join(publicPath, ".."));
+  const assetsKey = "assets.json";
+  const assetsPath = Path.join(publicPath, "..");
+  const storage = makeSourceStorage(assetsPath);
   if (shouldWatch) {
     void storage.watch(async (event, key) => {
-      if (event === "update" && key === indexKey) {
+      if (event === "update" && key === assetsKey) {
         await load();
       }
     });
   }
   const assets = {};
   async function load() {
-    const data = await storage.getItem(indexKey);
+    const data = await storage.getItem(assetsKey);
     Object.assign(assets, data || {});
   }
   const save = debounce(function() {
-    void storage.setItem(indexKey, assets);
+    void storage.setItem(assetsKey, assets);
   }, 50);
   function resolveAsset(content, relAsset, registerContent = false) {
     const srcDir = Path.dirname(content._file);
@@ -447,8 +461,19 @@ function makeAssetsManager(publicPath, shouldWatch = true) {
     }
     return asset;
   }
+  const init = () => {
+    if (Fs.existsSync(publicPath)) {
+      const names = Fs.readdirSync(publicPath);
+      for (const name of names) {
+        if (!/^\.git(ignore|keep)$/.test(name)) {
+          removeEntry(Path.join(publicPath, name));
+        }
+      }
+    }
+  };
   void load();
   return {
+    init,
     setAsset,
     getAsset,
     removeAsset,
@@ -521,24 +546,29 @@ const meta = {
 const module = defineNuxtModule({
   meta,
   defaults: {
-    imageSize: "style",
+    imageSize: "",
     contentExtensions: "md csv ya?ml json",
     debug: false
   },
   async setup(options, nuxt) {
     const buildPath = nuxt.options.buildDir;
-    const assetsPath = Path.join(buildPath, "content-assets");
-    const publicPath = Path.join(assetsPath, "public");
-    const contentPath = Path.join(buildPath, "content-cache/parsed");
+    const modulesPath = nuxt.options.modulesDir.find((path) => Fs.existsSync(`${path}/nuxt-content-assets/cache`)) || "";
+    if (!modulesPath) {
+      warn("Unable to find cache folder!");
+      if (nuxt.options.srcDir.endsWith("/playground")) {
+        warn('Run "npm run dev:setup" to generate a new cache folder');
+      }
+    }
+    const cachePath = modulesPath ? Path.resolve(modulesPath, "nuxt-content-assets/cache") : Path.resolve(buildPath, "content-assets");
+    const publicPath = Path.join(cachePath, "public");
+    const contentPath = Path.join(buildPath, "content-cache");
     const isDev = !!nuxt.options.dev;
     const isDebug = !!options.debug;
     if (isDebug) {
-      log("Removing cache folders...");
+      log("Cleaning content-cache");
+      log(`Cache path: "${Path.relative(".", cachePath)}"`);
     }
-    removeFolder(Path.join(buildPath, "content-cache"));
-    removeFolder(assetsPath);
-    createFolder(`${assetsPath}/public`);
-    writeFile(`${assetsPath}/nuxt.config.ts`, "export default {}");
+    removeEntry(contentPath);
     const { contentExtensions } = options;
     if (contentExtensions) {
       nuxt.options.content ||= {};
@@ -550,7 +580,7 @@ const module = defineNuxtModule({
     }
     const imageSizes = matchTokens(options.imageSize);
     const sources = Array.from(nuxt.options._layers).map((layer) => layer.config?.content?.sources).reduce((output, sources2) => {
-      if (sources2) {
+      if (sources2 && !Array.isArray(sources2)) {
         Object.assign(output, sources2);
       }
       return output;
@@ -565,6 +595,7 @@ const module = defineNuxtModule({
       }
     }
     const assets = makeAssetsManager(publicPath, isDev);
+    assets.init();
     function onAssetChange(event, absTrg) {
       let src = "";
       let width;
@@ -577,7 +608,7 @@ const module = defineNuxtModule({
         if (oldAsset) {
           if (oldAsset.width !== newAsset.width || oldAsset.height !== newAsset.height) {
             newAsset.content.forEach(async (id) => {
-              const path = Path.join(contentPath, toPath(id));
+              const path = Path.join(contentPath, "parsed", toPath(id));
               rewriteContent(path, newAsset);
             });
           }
@@ -594,7 +625,7 @@ const module = defineNuxtModule({
       }
     }
     addPlugin(resolve("./runtime/sockets/plugin"));
-    const socket = isDev ? await setupSocketServer("content-assets") : null;
+    const socket = isDev && nuxt.options.content?.watch !== false ? await setupSocketServer("content-assets") : null;
     const managers = {};
     for (const [key, source] of Object.entries(sources)) {
       if (isDebug) {

package/dist/runtime/assets/public.d.ts

@@ -3,10 +3,11 @@ import type { ParsedContent, AssetConfig } from '../../types';
  * Manages the public assets
  */
 export declare function makeAssetsManager(publicPath: string, shouldWatch?: boolean): {
+    init: () => void;
     setAsset: (path: string) => AssetConfig;
     getAsset: (path: string) => AssetConfig | undefined;
     removeAsset: (path: string) => AssetConfig | undefined;
-    resolveAsset: (content: ParsedContent, relAsset: string, registerContent?: boolean) => AssetConfig;
+    resolveAsset: (content: ParsedContent, relAsset: string, registerContent?: boolean) => Partial<AssetConfig>;
     dispose: () => Promise<void>;
 };
 /**

package/dist/runtime/assets/public.mjs

@@ -1,26 +1,28 @@
+import * as Fs from "fs";
 import Path from "crosspath";
 import getImageSize from "image-size";
 import debounce from "debounce";
 import { hash } from "ohash";
 import { makeSourceStorage } from "./source.mjs";
-import { isImage, warn, log } from "../utils/index.mjs";
+import { isImage, warn, log, removeEntry } from "../utils/index.mjs";
 export function makeAssetsManager(publicPath, shouldWatch = true) {
-  const indexKey = "assets.json";
-  const storage = makeSourceStorage(Path.join(publicPath, ".."));
+  const assetsKey = "assets.json";
+  const assetsPath = Path.join(publicPath, "..");
+  const storage = makeSourceStorage(assetsPath);
   if (shouldWatch) {
     void storage.watch(async (event, key) => {
-      if (event === "update" && key === indexKey) {
+      if (event === "update" && key === assetsKey) {
         await load();
       }
     });
   }
   const assets = {};
   async function load() {
-    const data = await storage.getItem(indexKey);
+    const data = await storage.getItem(assetsKey);
     Object.assign(assets, data || {});
   }
   const save = debounce(function() {
-    void storage.setItem(indexKey, assets);
+    void storage.setItem(assetsKey, assets);
   }, 50);
   function resolveAsset(content, relAsset, registerContent = false) {
     const srcDir = Path.dirname(content._file);
@@ -62,8 +64,19 @@ export function makeAssetsManager(publicPath, shouldWatch = true) {
     }
     return asset;
   }
+  const init = () => {
+    if (Fs.existsSync(publicPath)) {
+      const names = Fs.readdirSync(publicPath);
+      for (const name of names) {
+        if (!/^\.git(ignore|keep)$/.test(name)) {
+          removeEntry(Path.join(publicPath, name));
+        }
+      }
+    }
+  };
   void load();
   return {
+    init,
     setAsset,
     getAsset,
     removeAsset,

package/dist/runtime/utils/fs.d.ts

@@ -5,3 +5,5 @@ export declare function copyFile(src: string, trg: string): void;
 export declare function removeFile(src: string): void;
 export declare function createFolder(path: string): void;
 export declare function removeFolder(path: string): void;
+export declare function removeEntry(path: string): void;
+export declare function isFile(path: string): any;

package/dist/runtime/utils/fs.mjs

@@ -30,3 +30,15 @@ export function removeFolder(path) {
     Fs.rmSync(path, { recursive: true, force: true });
   }
 }
+export function removeEntry(path) {
+  if (Fs.existsSync(path)) {
+    if (isFile(path)) {
+      removeFile(path);
+    } else {
+      removeFolder(path);
+    }
+  }
+}
+export function isFile(path) {
+  return Fs.lstatSync(path).isFile();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-content-assets",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "description": "Enable locally-located assets in Nuxt Content",
   "repository": "davestewart/nuxt-content-assets",
   "license": "MIT",
@@ -15,16 +15,23 @@
   "main": "./dist/module.cjs",
   "types": "./dist/types.d.ts",
   "files": [
+    "cache",
     "dist"
   ],
   "scripts": {
+    "dev:setup": "cpy cache playground/node_modules/nuxt-content-assets && cpy \"cache/**\" playground/.nuxt/content-assets",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare",
+
     "dev": "nuxi dev playground",
-    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
     "dev:generate": "nuxi generate playground",
     "dev:build": "nuxi build playground",
     "dev:preview": "nuxi preview playground",
-    "release:dry": "npm run lint && npm run test && nuxt-module-build build && npm publish --dry-run",
-    "release": "npm run lint && npm run test && nuxt-module-build build && changelogen --release && npm publish && git push --follow-tags",
+
+    "build": "nuxt-module-build build",
+    "release:setup": "npm run lint && npm run test && npm run build",
+    "release:dry": "npm run release:setup && npm publish --dry-run",
+    "release": "npm run release:setup && npm publish",
+
     "lint": "eslint .",
     "test": "vitest run",
     "test:watch": "vitest watch"
@@ -44,20 +51,21 @@
     "@nuxt/content": "^2.0.0"
   },
   "devDependencies": {
-    "@types/node": "^20.12.4",
     "@nuxt/devtools": "latest",
     "@nuxt/eslint-config": "^0.2.0",
     "@nuxt/module-builder": "^0.5.5",
     "@nuxt/schema": "^3.11.2",
     "@nuxt/test-utils": "^3.12.0",
+    "@types/debounce": "^1.2.1",
+    "@types/node": "^20.12.4",
+    "@types/ws": "^8.5.10",
     "changelogen": "^0.5.5",
+    "cpy-cli": "^5.0.0",
     "eslint": "^8.57.0",
     "nuxt": "^3.11.2",
-    "vitest": "^1.4.0",
-    "@types/debounce": "^1.2.1",
-    "@types/ws": "^8.5.10"
+    "vitest": "^1.4.0"
   },
   "engines": {
     "node": ">=16.0.0"
   }
-}
+}