During full static generation, download all remote images and add them to the dist folder, replacing file names in html and static payloads

generation, nuxt, nuxt-module, vue, webpack
npm install nuxt-magpie@0.0.18



npm version npm downloads Github Actions CI Codecov License

Build module for Nuxt.js to download remote images and include them as local files in the generated build when performing full static generation.

📖 Release Notes

🐦 Shiny!

Magpie aims to take Nuxt's full static generation a step further, to create a standalone build with no API calls and no remote image assets.


  • Downloads local copies of all remote images to your /dist folder
  • For each generated route, replaces all image urls in the page's html and payload/state to use the local copies
  • Use it with a locally hosted CMS to create a build ready to be deployed on static hosts (e.g. Netlify)
  • Requires nuxt version >= 2.14.0

Before starting

In its current version, even with full static generation enabled, nuxt still runs the fetch and asyncData calls when navigating to another route (as documented here). To prevent these calls from overriding the urls replaced by magpie, you can add a check in your fetch or asyncData to bail fetching if the requested data is already available.


  1. Add nuxt-magpie dependency to your project
yarn add nuxt-magpie # or npm install nuxt-magpie
  1. Add nuxt-magpie to the buildModules section of nuxt.config.js
  buildModules: [
    // Simple usage

    // With options
        /* module options */
  1. Enable full static generation in nuxt.config.js:
  ssr: true,
  target: 'static'
  1. Run nuxt generate


All options and their default values:

  path: '/_images', // dir inside /dist where downloaded images will be saved
  extensions: ['jpg', 'jpeg', 'gif', 'png', 'webp'],
  baseUrl: '', // only download images from a certain url (e.g. your backend url)
  verbose: false, // show additional log info
  concurrency: 10, // max concurrent image downloads
  keepFolderStructure: false, // re-creates original image paths when saving local copies
  replaceInChunks: true, // attempts to replace image urls in the generated javascript chunks
  alias: null // see below for details


You can provide aliases to be replaced before image lookup. For example, Strapi doesn't return the full image urls when using the default upload provider, but instead uses the format /uploads/image-name.

You can use the alias option to make sure all image paths are parsed correctly:

  /* ... Magpie options */
  alias: {
    '/uploads': 'http://localhost:1337/uploads'


  1. Clone this repository
  2. Install dependencies using yarn install or npm install
  3. Start development server using npm run dev


MIT License

Copyright (c) Emilio Bondioli