Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
300 lines (207 loc) · 6.75 KB

CONTRIBUTING.md

File metadata and controls

300 lines (207 loc) · 6.75 KB
Raw

Contributing to astro-aws

Thank you for your interest in contributing to astro-aws! This document provides guidelines and instructions for contributing to the project.

Table of Contents

Getting Started

Prerequisites

  • Node.js: Version 22.x or 24.x
  • Bun: Version 1.3.5 (specified in package.json)
  • Git: For version control
  • AWS Account: For testing infrastructure deployments (optional, but recommended)

Fork and Clone

  1. Fork the repository on GitHub
  2. Clone your fork: 
    git clone ssh://git@github.com/YOUR_USERNAME/astro-aws.git
cd astro-aws
  3. Add the upstream repository: 
    git remote add upstream ssh://git@github.com/lukeshay/astro-aws.git

Development Setup

Install Dependencies

This project uses Bun as the package manager. Install dependencies:

bun install

Build the Project

Build all packages:

bun run build

Build a specific package:

bun run build:one @astro-aws/adapter

Run Development Server

Start development servers:

bun run dev

Start a specific workspace:

bun run dev:one @astro-aws/examples-base

Project Structure

This is a monorepo managed with Bun workspaces and Turbo:

astro-aws/
├── apps/              # Applications
│   ├── docs/         # Documentation site
│   └── infra/        # AWS CDK infrastructure
├── examples/         # Example Astro applications
│   └── base/         # Base example
├── packages/         # Published packages
│   ├── adapter/      # Astro adapter for AWS Lambda
│   └── constructs/   # AWS CDK constructs
└── scripts/          # Build and utility scripts

Key Packages

  • @astro-aws/adapter: The Astro adapter that handles deployment to AWS Lambda
  • @astro-aws/constructs: AWS CDK constructs for deploying Astro applications
  • @astro-aws/scripts: Internal build scripts

Making Changes

Creating a Branch

Create a new branch for your changes:

git checkout -b feature/your-feature-name

Or for bug fixes:

git checkout -b fix/your-bug-fix-name

Making Code Changes

  1. Make your changes in the appropriate package or workspace
  2. Ensure your code follows the project's code style (see Code Style)
  3. Add tests if you're adding new functionality
  4. Update documentation if needed

Testing Your Changes

Run tests:

bun run test

Run tests for a specific package:

bun run test:one @astro-aws/adapter

Formatting Code

Format code using Prettier:

bun run format

Testing

Running Tests

Run all tests:

bun run test

Run tests for a specific package:

bun run test:one @astro-aws/adapter

Testing Infrastructure

To test infrastructure changes, you'll need AWS credentials configured:

# Set AWS environment variables
export AWS_ACCOUNT=your-account-id
export AWS_REGION=us-east-1  # us-east-1 is recommended; us-west-2 may be restricted by SCPs in some accounts
export AWS_PROFILE=your-profile

# Build the infra package first
bun run build:one @astro-aws/infra

# Synthesize CDK stacks (PERSONAL environment targets your account with no custom domain)
AWS_PROFILE=$AWS_PROFILE AWS_ACCOUNT=$AWS_ACCOUNT AWS_REGION=$AWS_REGION npx cdk synth "AstroAWS-PERSONAL-*" --app "node --enable-source-maps dist/bin/infra.js"

# Deploy a specific stack (use with caution)
AWS_PROFILE=$AWS_PROFILE AWS_ACCOUNT=$AWS_ACCOUNT AWS_REGION=$AWS_REGION npx cdk deploy "AstroAWS-PERSONAL-Website-nodejs24-ssr" --require-approval never

Note: The PERSONAL environment deploys without custom domains or hosted zones, making it safe for sandbox/personal account testing. CDK must be bootstrapped in your target account and region first (npx cdk bootstrap).

Code Style

TypeScript

  • Use TypeScript for all code
  • Follow the existing code style
  • Use meaningful variable and function names
  • Add type annotations where helpful

Formatting

  • Code is formatted using Prettier
  • Run bun run format before committing
  • Prettier config: @lshay/prettier-config

Code Organization

  • Keep functions and classes focused and single-purpose
  • Add comments for complex logic
  • Follow existing patterns in the codebase

Submitting Changes

Commit Messages

Write clear, descriptive commit messages:

feat: add support for streaming SSR responses
fix: resolve CloudFront cache invalidation issue
docs: update getting started guide

Pull Request Process

  1. Update your branch: Make sure your branch is up to date with main:

    git checkout main
git pull upstream main
git checkout your-branch
git rebase main

  2. Run checks: Ensure all tests pass and code is formatted:

    bun run build
bun run test
bun run format

  3. Create Pull Request:

    • Push your branch to your fork
    • Create a pull request on GitHub
    • Fill out the PR template with:
      • Description of changes
      • Related issues (if any)
      • Testing performed
      • Screenshots (if applicable)

  4. Respond to feedback: Be responsive to code review comments and make requested changes

Pull Request Guidelines

  • Keep PRs focused and reasonably sized
  • Include tests for new features
  • Update documentation as needed
  • Ensure CI checks pass

Release Process

This project uses Changesets for version management.

Adding a Changeset

When making changes that should be released:

  1. Create a changeset:

    bun run changeset

  2. Select the packages affected

  3. Choose the type of change (major, minor, patch)

  4. Describe your changes

Release Workflow

The release process is handled by maintainers:

  1. Prepare release: bun run release:prepare

    • Builds all packages
    • Synthesizes CDK stacks
    • Versions packages based on changesets
    • Formats code

  2. Cut release: bun run release:cut

    • Deploys infrastructure
    • Publishes packages
    • Pushes tags

Additional Resources

Questions?

If you have questions or need help, please:

  • Open an issue on GitHub
  • Check existing issues and discussions
  • Review the documentation

Thank you for contributing to astro-aws! 🚀