@christian-wechsel/create-gcp-ts

An interactive CLI to scaffold production-ready TypeScript projects pre-configured for Google Cloud Platform (GCP), Terraform, and Cloud Build CI/CD.

Overview

Starting a new TypeScript project targeted for Google Cloud often requires repetitive configuration: setting up strict TypeScript builds, separating unit and integration test suites, configuring Docker/Cloud Build pipelines, provisioning Artifact Registry NPM repositories, and managing IAM roles.

create-gcp-ts automates this entire setup in seconds. It creates a standardized project structure with:

• Strict TypeScript configuration (tsconfig.json, tsconfig.prod.json, tsconfig.test.json).
• Jest test setup with separate configurations for unit tests (*.test.unit.ts) and integration tests (*.test.int.ts).
• Cloud Build 2nd Gen CI/CD pipeline (cloudbuild.yaml) with security audit, test execution, and dual-mode automated publishing:
  • Internal releases: Pushes to the main branch automatically publish packages to a private GCP Artifact Registry NPM repository.
  • Public releases: Pushes with Git tags (e.g., v1.0.0) automatically publish to npmjs.org using an NPM authentication token securely retrieved from GCP Secret Manager.
• Infrastructure as Code (Terraform) to manage Cloud Build triggers, IAM permissions, and Artifact Registry repositories.

Prerequisites

Before using the generated projects with Google Cloud and Terraform, ensure you have the following installed and configured:

1. Node.js: v20.x or v24.x (LTS recommended) and npm.

2. Google Cloud SDK (gcloud): Installed and authenticated:

   gcloud auth login
   gcloud auth application-default login

3. Terraform: >= 1.5.0 installed.

4. Cloud Build 2nd Gen GitHub Connection: For any template using automated build triggers (lib, node-project, cloud-run), your GitHub account and target repository must be connected to GCP Cloud Build (2nd Gen). This connection must be authorized in GitHub:

   • Create a 2nd Gen host connection in GCP Console > Cloud Build > Repositories.
   • Authorize and install the Google Cloud Build GitHub App on your GitHub account or organization.
   • Link the target GitHub repository under this connection so that Cloud Build receives push and tag webhook events.

Quick Start

Create an empty directory for your new project and run the generator:

mkdir my-new-project
cd my-new-project

# Run via npx
npx @christian-wechsel/create-gcp-ts@latest

# Or using npm create
npm create @christian-wechsel/gcp-ts@latest

The CLI will guide you through interactive prompts:

1. Project Name: Enter your package name (e.g., @my-org/my-package or my-app).
2. Project Type: Select the template that matches your target:
   • lib: TypeScript library / NPM package with dual publishing to GCP Artifact Registry and npmjs.
   • node-project: Standalone Node.js TypeScript application with Cloud Build triggers.
   • gcp-infrastructure: Shared GCP baseline infrastructure for NPM libraries (Artifact Registry NPM repo, Cloud Build Service Account, and IAM bindings).
   • server-infrastructure: Dedicated GCP project baseline for hosting servers (GCP project creation, enabled APIs, Artifact Registry Docker repository, Firestore native DB, Storage bucket, and Cloud Build SA).
   • server: Production-ready Express backend with Docker, Nginx reverse proxy, Certbot TLS, Firestore, and Compute Engine VM via IAP SSH.
   • cloud-run: Serverless Express microservice container on Google Cloud Run with autoscaling, IAM runtime identity, and Cloud Build CI/CD.

Project Templates

| Template | Intended Use | Key Features | | :--- | :--- | :--- | | lib | Reusable TypeScript libraries / NPM packages | Dual CI/CD publishing (internal GCP Artifact Registry on branch push, public npmjs on tag release), Jest test suites, .d.ts declaration generation. | | node-project | Node.js backend applications and services | TypeScript compilation, Jest testing, Cloud Build triggers for continuous integration and automated builds. | | gcp-infrastructure | Central GCP infrastructure setup for libraries | Creates shared Artifact Registry NPM repo, Cloud Build Service Account, and required IAM roles once per GCP project. | | server-infrastructure | Central GCP project baseline for server workloads | Creates a new GCP project, links billing, enables core APIs, provisions Artifact Registry Docker repository, Firestore DB, Storage bucket, and build service accounts. Outputs shared configuration for server instances. | | server | Express TypeScript backend server | Complete containerized Express stack with Docker Compose and Nginx reverse proxy, Compute Engine VM, custom VPC, IAP-secured SSH, automated TLS via init.sh, and local emulator/adapter fallbacks. | | cloud-run | Serverless microservice on Cloud Run | Express HTTP service containerized with multi-stage Docker, autoscaling (Cloud Run v2), least-privilege runtime service account, public invoker access, and Cloud Build automated CI/CD pipeline. Relies on server-infrastructure. |

Scaffolding & Setup Workflows

Libraries & Node Projects (lib, node-project)

1. First provision the shared library infrastructure once per GCP project using gcp-infrastructure.
2. Connect your GitHub account and repository via Cloud Build 2nd Gen (authorized in GitHub via the Google Cloud Build GitHub App).
3. Scaffold your lib or node-project.
4. Install dependencies (npm install).
5. Configure terraform.tfvars from terraform.tfvars.example and run terraform init && terraform apply to deploy Cloud Build triggers.

Server Deployments (server-infrastructure, server)

1. Create the Project Baseline (server-infrastructure):
   • Run terraform init && terraform apply to create the GCP project, enable APIs, and provision the Docker repository, Firestore database, and Cloud Storage bucket.
   • Note the outputs with terraform output (e.g. project_id, location, docker_repository, storage_bucket_name).
2. Deploy the Server Application (server):
   • Scaffold the server project and review configuration in .env and terraform.tfvars using the values from server-infrastructure.
   • Run terraform init && terraform apply to provision the VPC, static IP, and Compute Engine VM.
   • Point your DNS A-record to the generated vm_public_ip.
   • Ensure a container image has been built and pushed to Artifact Registry (e.g. via Cloud Build CI/CD).
   • Run the generated ssl_init_command (gcloud compute ssh ... --tunnel-through-iap --command="sudo /opt/<app-name>/init.sh") to acquire the TLS certificate and launch the container stack without exposing SSH port 22.

Cloud Run Deployments (server-infrastructure, cloud-run)

1. Create the Project Baseline (server-infrastructure):
   • Run terraform init && terraform apply to create the GCP project, enable APIs, and provision the Artifact Registry Docker repository and Cloud Build service account.
   • Note the outputs with terraform output (project_id, location, docker_repository, cloudbuild_service_account).
2. Connect GitHub to Cloud Build 2nd Gen:
   • In GCP Cloud Build > Repositories (2nd Gen), create a host connection and authorize the Google Cloud Build GitHub App on your GitHub account/organization.
   • Link the target GitHub repository under this connection.
3. Deploy the Cloud Run Service (cloud-run):
   • Scaffold the cloud-run project.
   • Populate terraform.tfvars from terraform.tfvars.example using the outputs from server-infrastructure alongside your GitHub connection details.
   • Run terraform init && terraform apply to provision the Cloud Run service, the dedicated runtime IAM identity, and the Cloud Build trigger.
   • Push code to your configured branch to trigger the automated build, container push to Artifact Registry, and zero-downtime deployment to Cloud Run.

Available NPM Scripts

Generated projects include standard scripts:

| Command | Description | | :--- | :--- | | npm run build | Compiles TypeScript using tsconfig.json into dist/. | | npm run build-prod | Performs a clean compilation using tsconfig.prod.json. | | npm test | Compiles test builds and runs all Jest tests. | | npm run test:unit | Executes only unit tests (*.test.unit.ts). | | npm run test:int | Executes only integration tests (*.test.int.ts). | | npm start | Executes the compiled application (node dist/index.js). | | npm run debug | Launches Node.js with the inspector enabled (--inspect-brk). | | npm run clean | Deletes previous build outputs in dist/. |

CI/CD Pipeline Workflow

The generated cloudbuild.yaml implements an automated release workflow:

flowchart TD
    A[Git Event] --> B{Event Type}
    B -->|Push to main branch| C[npm audit]
    B -->|Push tag v*.*.*| C
    C --> D[npm ci]
    D --> E[npm test]
    E --> F{Event Type}
    F -->|Branch Push| G[Fetch GCP OAuth2 Access Token]
    G --> H[Publish to GCP Artifact Registry]
    F -->|Tag Release| I[Fetch NPM_TOKEN from Secret Manager]
    I --> J[Publish to Public npmjs.org]

1. Security Audit: Runs npm audit --audit-level=high.
2. Dependency Installation: Runs clean installation with npm ci.
3. Tests: Executes all test suites via npm test.
4. Publishing:
   • Branch Push (main): Uses GCP OAuth token from the Cloud Build service account to publish to your private Artifact Registry.
   • Tag Release (v*): Fetches NPM_TOKEN from GCP Secret Manager and publishes publicly to npm.

License

This project is licensed under the MIT License.