Generated with Goldstack

S3, Terraform and TypeScript Boilerplate

Boilerplate for setting up the infrastructure for AWS S3 using Terraform and working with S3 using a simple TypeScript API.

const bucketName = await getBucketName();
const s3 = await connect();
await s3
  .putObject({
    Key: 'local.txt',
    Body: 'hello',
    Bucket: bucketName,
  })
  .promise();

This boilerplate has been automatically generated from the template:

AWS S3

Feel free to fork this repository and modify it for your needs, or use the Goldstack project builder to generate a boilerplate specifically generated for your project.

⚠️ Before forking this boilerplate, consider if you would want to start with a project that contains a server template as well, such as Serverless API or Serverless Express.js.

Getting Started

Thank you for using this boilerplate. For any questions or feedback, please be welcome to raise an issue on GitHub 🤗 .

1. Fork and clone the repository

Fork this repository and then clone the fork into your local machine.

For more information, see GitHub documentation - Fork a repo

2. Install required local dependencies

A few dependencies need to be available in your development system. Please verify they are present or install them.

• Node v18+
• Yarn v1.22.5+
• Docker v24+

Open a terminal and run the following commands:

node -v
yarn -v
docker --version

This should produce the following output:

If you need to install or update any of the dependencies, please see the following guides:

• Downloading and installing Node.js and npm
• Yarn Installation
• Install Docker for Windows / Install Docker for Mac

3. Initialise project and install NPM Dependencies

Run yarn in your project directory to install and download all dependencies.

The installation process should take around 3-10 minutes depending on the dependencies that need to be downloaded.

You can confirm everything was installed correctly by running yarn -v. This should show a yarn version of 3.0.0+.

4. Build modules

Make sure that the project compiles correctly by running yarn build your project directory:

Note that this command also ensures that all TypeScript project references are configured correctly.

5. Configure VSCode

In order to setup VSCode, open the project in VSCode.

VSCode may prompt you to ask if you trust the authors of the workspace. Respond with Yes.

You may also be asked if you want to install recommended extensions for this workspace. We recommend to do so since the template will be optimised to work with the suggested extensions.

If you want to install the necessary extensions manually, here are links to the extensions required:

• ESLint
• Prettier
• ZipFS (optional)

6. Initialise TypeScript

Locate a .ts or .tsx file in the workspace and open it. When asked whether to use the workspace TypeScript version, click Allow.

In the status bar on the bottom right-hand corner of the VSCode editor you should now see TypeScript.

7. AWS Infrastructure Configuration

If you want to setup your S3 infrastructure on AWS, you will need to make some changes to the configuration files included in this project.

Specifically, the goldstack.json in the packages/s3-1 folder.

{
  "$schema": "./schemas/package.schema.json",
  "name": "s3",
  "template": "s3",
  "templateVersion": "0.1.0",
  "configuration": {},
  "deployments": [
    {
      "name": "prod",
      "awsRegion": "us-west-2",
      "awsUser": "goldstack-dev",
      "configuration": {
        "bucketName": "goldstack-test-s3-bucket"
      },
      "tfStateKey": "s3-prod-40dd578eab44b83dc601.tfstate",
      "tfVersion": "1.1"
    }
  ]
}

The key property you will need to update is:

• deployments[0].configuration.bucketName

You also need to delete deployments[0].tfStateKey.

For more information on these configuration options, see Goldstack Documentation / S3 / Configure.

You will also need to ensure that you have a valid AWS user configure to deploy to AWS. For this, create a file in /config/infra/config.json (relative to project root).

{
  "users": [
    {
      "name": "goldstack-dev",
      "type": "apiKey",
      "config": {
        "awsAccessKeyId": "...",
        "awsSecretAccessKey": "...",
        "awsDefaultRegion": "us-west-2"
      }
    },
    {
      "name": "goldstack-prod",
      "type": "apiKey",
      "config": {
        "awsAccessKeyId": "...",
        "awsSecretAccessKey": "",
        "awsDefaultRegion": "us-west-2"
      }
    }
  ]
}

For more information on configuring your local AWS users, please see Goldstack Documentation / AWS Configuration.

Once your AWS user is configured you can run yarn infra up prod in the /packages/s3 folder. For more information on the infrastructure commands for this project, see Goldstack Documentation / S3 / Infrastructure.

8. Local Development

This boilerplate will come with a module that provides the functionalities for working with S3. This module is defined in packages/s3-1. Generally you won't have to make changes to this module during local development. Instead, create an additional npm module in the packages/ folder and then import the s3 module as one of the dependencies.

Then use the exported connect() and getBucketName() in your code to write and read data from S3:

    const bucketName = await getBucketName();
    const s3 = await connect();
    await s3
      .putObject({
        Key: 'local.txt',
        Body: 'hello',
        Bucket: bucketName,
      })
      .promise();
  });

The result of await connect() is an instance of AWS.S3.

9. Contribute to Goldstack

Have questions or ideas or want to contribute to the project? Please head over to github.com/goldstack/goldstack.