{"id":17431,"library":"ember-cli-deploy-s3-index","title":"Ember CLI Deploy S3 Index Plugin","description":"This plugin for Ember CLI Deploy specializes in uploading the `index.html` (bootstrap) file of an Ember application to an Amazon S3 bucket. It is commonly used as part of the 'lightning method' of deployment, where both application assets and the index file are served from S3. The current stable version is 4.0.3, with recent bug fixes focusing on robust S3 response handling, including 'NotFound' and empty responses. It integrates into the `ember-cli-deploy` pipeline, implementing `configure`, `upload`, `activate`, and `fetchRevisions` hooks. It's actively maintained with a moderate release cadence addressing bug fixes and minor enhancements, distinguishing itself by managing *only* the index file, often alongside `ember-cli-deploy-s3` which handles other application assets.","status":"active","version":"4.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/ember-cli-deploy/ember-cli-deploy-s3-index","tags":["javascript","ember-addon","ember-cli-deploy-plugin"],"install":[{"cmd":"npm install ember-cli-deploy-s3-index","lang":"bash","label":"npm"},{"cmd":"yarn add ember-cli-deploy-s3-index","lang":"bash","label":"yarn"},{"cmd":"pnpm add ember-cli-deploy-s3-index","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for building the Ember application before deployment as part of the Ember CLI Deploy pipeline.","package":"ember-cli-deploy-build","optional":false},{"reason":"Required for generating revision data, which is crucial for managing index file versions on S3.","package":"ember-cli-deploy-revision-data","optional":false},{"reason":"Recommended for displaying deployed revisions and managing activations, though not strictly required for core functionality.","package":"ember-cli-deploy-display-revisions","optional":true}],"imports":[{"note":"Ember CLI plugins are installed using `ember install` to integrate them correctly into the project's build system and hook into the deploy pipeline.","wrong":"npm install ember-cli-deploy-s3-index","symbol":"Installation","correct":"ember install ember-cli-deploy-s3-index"},{"note":"The plugin is configured via an object under the `ENV['s3-index']` key in your `config/deploy.js`. Use environment variables for sensitive AWS credentials.","symbol":"Configuration","correct":"// config/deploy.js\nENV['s3-index'] = {\n  accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '',\n  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '',\n  bucket: 'your-app-bucket',\n  region: 'us-east-1'\n};"},{"note":"The plugin runs automatically as part of the `ember deploy` pipeline once installed and configured. No direct JavaScript `import` or function call is typically made by users.","symbol":"Deployment Command","correct":"ember deploy <environment>"}],"quickstart":{"code":"ember install ember-cli-deploy-s3-index\n\n// Add the following configuration to config/deploy.js\n// Ensure ember-cli-deploy-build and ember-cli-deploy-revision-data are also installed and configured.\n// For production deployments, strongly recommend using environment variables or AWS profiles for credentials.\nENV['s3-index'] = {\n  accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '', // Placeholder: set this in your CI/CD or local environment\n  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '', // Placeholder: set this securely\n  bucket: 'my-ember-app-index-bucket',\n  region: 'us-east-1',\n  prefix: 'app-prefix' // Optional: deploys index.html into a sub-directory within the S3 bucket\n};\n\n// To run the deployment:\n// Ensure your AWS credentials (e.g., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION) are set as environment variables\n// or configured via an AWS profile.\n// Execute in your terminal: `ember deploy production`","lang":"javascript","description":"Demonstrates how to install the plugin and configure it in `config/deploy.js` for an Ember CLI project, preparing for index file deployment to AWS S3."},"warnings":[{"fix":"Always define separate and distinct configuration objects for `ENV.s3` and `ENV['s3-index']` in your `config/deploy.js`, even if properties like `bucket` or `region` are identical.","message":"Do NOT share a single configuration object between `ember-cli-deploy-s3` (for static assets) and `ember-cli-deploy-s3-index` (for index.html). The internal configuration parsing can lead to side effects and break your deployment pipeline if a shared object is used.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js environment to `14.* || 16.* || 18.* || >= 20`. Review and update your project's `package.json` dependencies to ensure compatibility with `ember-cli-deploy` and its ecosystem plugins.","message":"Version 3.0.0 introduced significant breaking changes, primarily updating Node.js version requirements and internal dependencies. Projects must meet the new Node.js compatibility.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"For production and secure deployments, prioritize using IAM roles for EC2 instances/CI environments or setting AWS credentials as environment variables over hardcoding them in configuration files.","message":"AWS SDK credential resolution: If `accessKeyId` and `secretAccessKey` are not explicitly defined in `config/deploy.js`, the plugin will fall back to standard AWS SDK credential resolution methods (e.g., environment variables like `AWS_ACCESS_KEY_ID`, shared credentials file, or IAM roles).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"In your `config/deploy.js`, explicitly set `ENV['s3-index'].acl = false;` to prevent the plugin from applying any ACLs during upload. Ensure your bucket policy grants appropriate public access if needed.","message":"By default, objects uploaded will have an ACL (Access Control List) of `public-read`. If you do not wish to apply any ACLs, you must explicitly set the `acl` option to `false`.","severity":"gotcha","affected_versions":">=4.0.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Verify that your AWS credentials are correct and that the associated IAM user or role has the required S3 permissions configured for the specified bucket and prefix in your AWS IAM console.","cause":"The AWS credentials (accessKeyId, secretAccessKey, profile, or IAM role) used by the plugin lack the necessary S3 permissions (e.g., `s3:PutObject`, `s3:GetObject`, `s3:ListBucket`) for the target bucket and prefix.","error":"Error: Access Denied"},{"fix":"Double-check the `filePattern` and `prefix` settings in `config/deploy.js`. Use the AWS S3 console or CLI to inspect your bucket contents and confirm the path and existence of expected index files and revision history.","cause":"The plugin attempted to fetch a previous revision of the index file from S3, but the file was not found at the expected location. This could be due to an incorrect `filePattern`, `prefix` configuration, or manual deletion of S3 objects.","error":"Error: The specified key does not exist."},{"fix":"Ensure your S3 bucket configuration is valid and accessible. Check the AWS Service Health Dashboard for S3 issues. This specific bug was addressed and resolved in plugin versions 4.0.2 and 4.0.3; upgrading the plugin might be necessary.","cause":"An unexpected empty response was received from AWS S3 during an operation (e.g., listing revisions). This might indicate an S3 misconfiguration, an intermittent AWS service issue, or a bug in previous plugin versions.","error":"Error: An empty S3 response was encountered."}],"ecosystem":"npm","meta_description":null}