{"id":29943379,"url":"https://github.com/sourcefuse/arc-tf-cdk-spa-host","last_synced_at":"2025-10-11T12:17:11.345Z","repository":{"id":194579300,"uuid":"644868502","full_name":"sourcefuse/arc-tf-cdk-spa-host","owner":"sourcefuse","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-12T07:36:09.000Z","size":206,"stargazers_count":2,"open_issues_count":15,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-09-27T13:41:54.546Z","etag":null,"topics":["arcbysf","cdktf","cloudfront","single-page-applications","terraform"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@arc-iac/tf-cdk-spa","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sourcefuse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-05-24T12:28:21.000Z","updated_at":"2024-03-19T04:48:46.000Z","dependencies_parsed_at":"2023-09-14T06:09:22.805Z","dependency_job_id":"b226253e-0713-4747-aeec-03c8abba24d8","html_url":"https://github.com/sourcefuse/arc-tf-cdk-spa-host","commit_stats":null,"previous_names":["sourcefuse/arc-tf-cdk-spa-host"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sourcefuse/arc-tf-cdk-spa-host","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Farc-tf-cdk-spa-host","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Farc-tf-cdk-spa-host/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Farc-tf-cdk-spa-host/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Farc-tf-cdk-spa-host/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sourcefuse","download_url":"https://codeload.github.com/sourcefuse/arc-tf-cdk-spa-host/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Farc-tf-cdk-spa-host/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279007142,"owners_count":26084246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arcbysf","cdktf","cloudfront","single-page-applications","terraform"],"created_at":"2025-08-03T02:15:12.125Z","updated_at":"2025-10-11T12:17:11.315Z","avatar_url":"https://github.com/sourcefuse.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS Static and Single-Page Application (SPA) Deployment with CDKTF\n\nSimplify the deployment of your static websites and Single-Page Applications (SPAs) to Amazon Web Services (AWS) S3 and CloudFront using the Cloud Development Kit for Terraform (CDKTF) with TypeScript. This package leverages the power of the Cloud Development Kit (CDK) to define and manage AWS resources effortlessly.\n\nWith support for both traditional static websites and modern SPAs, including flexible routing options, our toolkit makes it easier than ever to host and deploy your web applications on AWS infrastructure. Take advantage of AWS S3 and CloudFront's performance, scalability, and reliability while streamlining your deployment workflow.\n\n## Prerequisites\n\nBefore you begin, ensure you have the following prerequisites in place:\n\n- **AWS Account:** You'll need an AWS account to deploy infrastructure and access necessary services.\n- **Node.js and npm:** Install Node.js and npm (Node Package Manager) on your local development machine.\n- **Terraform:** Install the Terraform CLI on your local development machine.\n- **AWS CLI:** Install the AWS CLI and configure it with your AWS credentials.\n- **Hosted Zone in Route 53:** Set up a hosted zone in AWS Route 53 for your custom domain.\n\n## Installation\n\n```bash\nnpm install @arc-iac/tf-cdk-spa\n```\n\n## Migrating from v1 -\u003e v2\n\nThe class name `CloudFrontStaticWebsiteStack` has been updated to `CloudfrontSPAWebsiteStack`. The `CloudFrontSPAWebsiteStack` is now more suitable for deploying websites with a single index document, which is often the case for Single Page Applications (SPAs) built using technologies like React.\n\nIf you need to deploy a static website that has multiple index documents, you can use the `CloudfrontStaticWebsiteStack` class. More details on usage can be found in the [exports section](#exports).\n\n## Exports\n\nThis package exports the following classes:\n\n1. [CloudFrontSPAWebsiteStack](#cloudfrontspawebsitestack)\n2. [CloudfrontStaticWebsiteStack](#cloudfrontstaticwebsitestack)\n\n### CloudFrontSPAWebsiteStack\n\nThe `CloudFrontSPAWebsiteStack` class allows you to easily set up and deploy Single Page Applications (SPAs) with a single index document using AWS CloudFront, S3, OAC, ACM, and Route 53. This stack simplifies the deployment process and ensures your SPA is highly available and globally accessible.\n\n#### Usage example\n\n```typescript\nimport { CloudFrontSPAWebsiteStack } from \"@arc-iac/tf-cdk-spa\";\nimport { App } from \"cdktf\";\n\nconst app = new App();\nnew CloudFrontSPAWebsiteStack(app, \"spa-host\");\napp.synth();\n```\n\n### CloudfrontStaticWebsiteStack\n\nThe `CloudfrontStaticWebsiteStack` class provides a flexible and robust solution for hosting static websites on AWS using CloudFront, S3, ACM, and Route 53. This stack is ideal for deploying websites with multiple directories, each having its own index document.\n\n#### Usage Example\n\n```typescript\nimport { CloudfrontStaticWebsiteStack } from \"@arc-iac/tf-cdk-spa\";\n\n// Create an instance of the CloudfrontStaticWebsiteStack\nconst staticWebsiteStack = new CloudfrontStaticWebsiteStack(\n  app,\n  \"MyStaticWebsiteStack\"\n);\n\n// Customize the stack's configuration as needed\n// You can choose to skip this step and use the default configuration.\nstaticWebsiteStack.awsConfig = {\n  region: \"us-west-2\",\n  profile: \"my-aws-profile\",\n};\n\nstaticWebsiteStack.s3BucketConfig = {\n  bucket: \"my-static-website-bucket\",\n  tags: {\n    Terraform: \"true\",\n    Environment: \"prod\",\n  },\n};\n\n// Initialize and deploy the stack\nstaticWebsiteStack.init();\n```\n\n## Usage\n\nThe following example demonstrates how to deploy a site (using the default configurations used in this package).\n\n1. [Choose a suitable Class](#choose-a-suitable-class)\n2. [Create a cdk entrypoint file](#create-a-file-for-cdk-entrypoint)\n3. [Create a cdktf.json file](#create-a-cdktfjson-file)\n4. [Configure the Environment Variables](#configure-the-environment-variables)\n5. [Deploy the infrastructure](#deploy-the-infrastructure)\n6. [Verify the deployment](#verify-the-deployment)\n\n### Choose a suitable class\n\nSelect a suitable class for your use case. More on classes in [exports section](#exports).\nIn this example I have used `CloudfrontStaticWebsiteStack` but you may choose as per your need.\n\n### Create a file for CDK entrypoint\n\nTo establish the CDK entry point, you'll need to create a TypeScript file named main.ts. Feel free to give it a name that suits your preference, just ensure you replace the name consistently throughout.\nAdd the following TypeScript code:\n\n```typescript\nimport { CloudFrontSPAWebsiteStack } from \"@arc-iac/tf-cdk-spa\";\nimport { App } from \"cdktf\";\n\nconst app = new App();\nnew CloudFrontSPAWebsiteStack(app, \"spa-host\"); // You can change the stack name (\"spa-host\") as needed.\napp.synth();\n```\n\nThis code initializes an instance of the App class, then creates an instance of your custom `CloudFrontSPAWebsiteStack`. You can tailor the stack name by changing the second argument of the new `CloudFrontSPAWebsiteStack()` line (\"spa-host\" in this example). Lastly, the app.synth() function generates the Terraform configuration based on your CDK code.\n\n### Create a cdktf.json file\n\nA cdktf project requires a cdktf.json file. Using the cdktf.json file you can supply custom configuration settings for your application.\nYou can use the following content in your cdktf.json\n\n```json\n{\n  \"language\": \"typescript\",\n  \"app\": \"npx ts-node main.ts\",\n  \"projectId\": \"a-random-uuid\"\n}\n```\n\nYou can learn more about cdktf.json [here](https://developer.hashicorp.com/terraform/cdktf/create-and-deploy/configuration-file).\n\n### Configure the [Environment Variables](#environment-variables)\n\nThe example below shows a configuration of env variables.\n\n```environment\nAWS_REGION=us-east-1\nS3_BUCKET_NAME=my-custom-s3-bucket\nCUSTOM_DOMAIN=my-custom-domain-name.com\nHOSTED_ZONE_ID=Z00000000\nRELATIVE_PATH_TO_BUILD_DIR=../build\n```\n\n### Deploy the Infrastructure\n\n```bash\nnpx cdktf deploy spa-host\n```\n\nThis command leverages Terraform and CDK to create AWS resources based on the code in `main.ts`. The deployment might take a few minutes.\n\n**Note:** If you have multiple stacks or custom stack names, use `cdktf deploy \u003cstack-name\u003e`.\n\n### Verify the Deployment\n\nAfter successful deployment, access your SPA through the custom domain specified in `CUSTOM_DOMAIN`. Keep in mind that CloudFront might take some time to fully activate. If you encounter an `AccessDenied` error, it's likely due to ongoing CloudFront provisioning. Wait about 15-20 minutes before accessing your resources.\n\n## Environment Variables\n\nThe deployment process relies on several environment variables. Create a `.env` file in the project's root directory and set the following variables:\n\n| Environment Variable         | Default Value | Description                                                                                                                                 |\n| ---------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |\n| `AWS_REGION`                 | `us-east-1`   | AWS region for deployment                                                                                                                   |\n| `AWS_PROFILE`                | `default`     | AWS profile for authentication and authorization                                                                                            |\n| `S3_BUCKET_NAME`             | N/A           | S3 bucket name for storing SPA files                                                                                                        |\n| `CUSTOM_DOMAIN`              | N/A           | Custom domain for the SPA                                                                                                                   |\n| `HOSTED_ZONE_ID`             | N/A           | Route 53 hosted zone ID for the custom domain                                                                                               |\n| `RELATIVE_PATH_TO_BUILD_DIR` | `../build`    | Relative path to the SPA build directory                                                                                                    |\n| `REFERER_SECRET`             | N/A           | A secret key used in the HTTP headers to control access to your s3 bucket objects (Required only for `CloudfrontStaticWebsiteStack` class). |\n\nIf any variables are not provided, the default values mentioned above will be used.\n\n## Cleanup\n\nTo remove deployed resources from AWS, run:\n\n```bash\nnpx cdktf destroy spa-host\n```\n\nUse this command to destroy infrastructure created during deployment. Confirm the destruction when prompted. Replace `spa-host` with your stack names if customized.\n\n## License\n\nThis code is licensed under the MPL-2.0 license.\n\n## References\n\n- [Terraform](https://www.terraform.io/)\n- [CDK for Terraform](https://developer.hashicorp.com/terraform/cdktf)\n- [CDKTF AWS Provider](https://github.com/cdktf/cdktf-provider-aws)\n- [AWS CLI](https://aws.amazon.com/cli/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsourcefuse%2Farc-tf-cdk-spa-host","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsourcefuse%2Farc-tf-cdk-spa-host","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsourcefuse%2Farc-tf-cdk-spa-host/lists"}