Vue CLI S3 Deployment Plugin

4.0.0-rc3 · active · verified Sun Apr 19

Vue CLI Plugin S3 Deploy is a utility designed to streamline the deployment of built Vue.js applications to AWS S3 buckets. It offers comprehensive features including support for custom AWS regions, management of AWS credential profiles and environment variables, configuration for S3 static site hosting, and concurrent uploads to enhance deployment speed. Additionally, it integrates with CloudFront for cache invalidation, applies correct `Cache-Control` metadata for Progressive Web Apps (PWAs) and Service Workers, handles GZIP compression, and allows for configurable deployment paths, enabling multiple Vue applications within a single S3 bucket. The package is currently in its 4.x release candidate series, with `4.0.0-rc3` being the latest specified release candidate, indicating active development towards a stable version. Given it's a CLI plugin, its release cadence is tied to Vue CLI updates and community contributions. A key differentiator is its deep integration with the Vue CLI ecosystem, providing a guided setup and `vue.config.js` based configuration.

Common errors

```
TypeError: The 'compilation' argument must be an instance of Compilation
```
cause Outdated lockfile or `node_modules` after a Vue CLI upgrade (e.g., to v4 or v5) where Webpack 5 was introduced.

fix Remove `package-lock.json` or `yarn.lock` and the `node_modules` directory, then run `npm install` or `yarn install` to reinstall dependencies with the correct versions.
```
404 Not Found (for sub-routes after deployment)
```
cause When using Vue Router in history mode, direct access to sub-paths (e.g., `/dashboard`) results in a 404 because S3 static website hosting doesn't have a physical file at that path.

fix Configure S3 static website hosting to redirect 4xx errors to `index.html`. In `vue.config.js`, set `staticErrorPage: 'index.html'` for `pluginOptions.s3Deploy`. For CloudFront, set up custom error responses to redirect 403/404 to `/index.html` with an HTTP 200 response.
```
Error: Missing credentials in config
```
cause The AWS SDK, used by the plugin, cannot find valid AWS credentials in the environment or specified profile.

fix Ensure `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` (and `AWS_SESSION_TOKEN` for temporary credentials) environment variables are set, or that a valid AWS profile is configured in `~/.aws/credentials` and specified via `awsProfile` in `vue.config.js`.
```
DeployPath failures / files not deploying to correct S3 folder
```
cause Issues with `deployPath` configuration, particularly observed in earlier release candidates of `4.x`.

fix Ensure `deployPath` is correctly specified in `vue.config.js`. If using `4.0.0-rc3` or earlier, consider upgrading to `4.0.0-rc4` or later, which includes fixes for `deployPath` issues.

Warnings

gotcha The `vue-cli-plugin-s3-deploy` package targets Vue CLI projects. As Vue CLI is now in maintenance mode, new Vue projects are recommended to use Vite. This plugin may not be suitable for Vite-based projects.
Fix: For new projects, consider native AWS S3 sync commands or alternative deployment solutions for Vite-based applications. For existing Vue CLI projects, proceed with this plugin.
breaking Version `4.x` of this plugin is currently in release candidate status (`4.0.0-rc3`, `4.0.0-rc4`). While functional, it is not yet considered stable and may contain unresolved issues or further breaking changes before a stable `4.0.0` release.
Fix: Review the plugin's GitHub repository for the latest release status and changelog. For production environments, consider sticking to the latest stable `3.x` branch if available, or thoroughly testing `4.x` RCs.
breaking If upgrading Vue CLI to `v4` or `v5`, several underlying breaking changes from Vue CLI itself (Webpack 5, Node.js/NPM version requirements) can impact plugin functionality. For instance, Node.js 8-11 and NPM 5 are no longer supported by Vue CLI 4.
Fix: Ensure your Node.js and npm versions meet the Vue CLI requirements. If encountering `TypeError: The 'compilation' argument must be an instance of Compilation` errors, delete `node_modules` and `package-lock.json`/`yarn.lock` and reinstall.
gotcha AWS credentials (e.g., `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` environment variables or `~/.aws/credentials` profile) must be correctly configured in your deployment environment for the plugin to authenticate with S3 and CloudFront.
Fix: Set up AWS credentials globally or specify an `awsProfile` in `vue.config.js`. Use environment variables (`VUE_APP_S3D_AWS_PROFILE`, `VUE_APP_S3D_REGION`, `VUE_APP_S3D_BUCKET`, `VUE_APP_S3D_CLOUDFRONT_ID`) for per-environment overrides.
breaking In `v2.0.0`, the plugin refactored its configuration to be entirely within `vue.config.js`, moving away from previous configuration storage methods. Older configurations will not be compatible.
Fix: If migrating from a version older than `2.0.0`, recreate your configuration using `vue.config.js` as described in the documentation. Run `vue invoke s3-deploy` to help generate the basic structure.

Install

npm install vue-cli-plugin-s3-deploy npm
yarn add vue-cli-plugin-s3-deploy yarn
pnpm add vue-cli-plugin-s3-deploy pnpm

Quickstart

Shows how to install, configure in `vue.config.js`, and deploy a Vue.js app to S3.

# Install the plugin
npm install -D vue-cli-plugin-s3-deploy
# OR
yarn add -D vue-cli-plugin-s3-deploy

# Invoke the plugin to set up initial configuration and package.json script
vue invoke s3-deploy

// vue.config.js
module.exports = {
  pluginOptions: {
    s3Deploy: {
      awsProfile: process.env.VUE_APP_S3D_AWS_PROFILE ?? 'default', // Use 'default' profile or env var
      region: process.env.VUE_APP_S3D_REGION ?? 'us-east-1',
      bucket: process.env.VUE_APP_S3D_BUCKET ?? 'your-s3-bucket-name',
      createBucket: false,
      staticHosting: true,
      staticIndexPage: 'index.html',
      staticErrorPage: 'index.html', // Essential for Vue Router history mode
      assetPath: 'dist',
      deployPath: '/',
      pwa: true,
      enableCloudfront: true,
      cloudfrontId: process.env.VUE_APP_S3D_CLOUDFRONT_ID ?? '',
      cloudfrontPaths: ['/*', '/index.html']
    }
  }
};

# Build and deploy your app (requires AWS credentials configured)
npm run deploy
# OR
yarn deploy

view raw JSON →