How to Upload Files to Google Cloud Storage from Node.js

Google Cloud Storage holds the files a backend accepts from users: avatars, invoices, exports. Writing one object from Node.js takes two lines. The parts that slow teams down are around it: signed URLs that fail on Cloud Run because there is no key file, buckets created by hand per environment, and large uploads that hit the request size limit of the API in front of them.

This guide builds an attachments API in TypeScript with three endpoints: one that hands the browser a signed upload URL, one that accepts small files directly, and one that returns a short-lived download link. The first version uses Encore (a tool that works alongside your framework), the second the official @google-cloud/storage client.

Cloud Storage uploads at a glance

Each option is covered below, starting with Encore.

Declaring a bucket that becomes Cloud Storage with Encore

Encore is a tool that works alongside your framework for TypeScript and Go, with a platform that provisions and deploys into your own AWS or GCP account. A Bucket declared in a service becomes a Cloud Storage bucket on GCP and an S3 bucket on AWS. Cloud access sits with Encore's service identity, not the agent.

The whole attachments service:

// uploads/uploads.ts
import { api } from "encore.dev/api";
import { Bucket } from "encore.dev/storage/objects";

// A Cloud Storage bucket on GCP, an S3 bucket on AWS.
export const attachments = new Bucket("attachments", { versioned: false });

// Returns a short-lived URL the browser can PUT the file to directly.
export const uploadUrl = api(
  { expose: true, method: "POST", path: "/attachments/upload-url" },
  async ({ name }: { name: string }): Promise<{ key: string; url: string }> => {
    const key = `${Date.now()}-${name.replace(/[^\w.-]/g, "_")}`;
    const { url } = await attachments.signedUploadUrl(key, { ttl: 900 });
    return { key, url };
  },
);

// Small files can also go through the API.
export const upload = api.raw(
  { expose: true, method: "PUT", path: "/attachments/:key" },
  async (req, resp) => {
    const key = (req.url ?? "").split("/").pop()!;
    const chunks: Buffer[] = [];
    for await (const chunk of req) chunks.push(chunk as Buffer);
    const attrs = await attachments.upload(key, Buffer.concat(chunks), {
      contentType: req.headers["content-type"] ?? "application/octet-stream",
    });
    resp.writeHead(201, { "Content-Type": "application/json" });
    resp.end(JSON.stringify({ key, size: attrs.size }));
  },
);

export const downloadUrl = api(
  { expose: true, method: "GET", path: "/attachments/:key/download-url" },
  async ({ key }: { key: string }): Promise<{ url: string }> => {
    const { url } = await attachments.signedDownloadUrl(key, { ttl: 300 });
    return { url };
  },
);

encore run serves the bucket from a local object store, signed URLs included, so the browser flow works on a laptop:

On deploy, the signed URLs point at Cloud Storage, and there is no key file or Token Creator grant to set up. For files that should be public, such as product images, new Bucket("images", { public: true }) and publicUrl(key) serve them through Cloud CDN. The object storage docs list the rest of the API, including list, remove and attrs.

A coding agent asked to "let users attach files" can add the bucket, the endpoints and the client call in one change, then exercise the upload under encore run.

The deployment guide covers how a push becomes a running service with its bucket.

The same API with @google-cloud/storage

With the Node.js client, the bucket must exist first and the Cloud Run service account needs roles/storage.objectUser on it. Signing URLs on Cloud Run calls the IAM signBlob API, so the service account also needs roles/iam.serviceAccountTokenCreator on itself:

gcloud storage buckets create gs://acme-attachments-prod \
  --location=europe-west1 --uniform-bucket-level-access

gcloud storage buckets add-iam-policy-binding gs://acme-attachments-prod \
  --member="serviceAccount:attachments@my-project.iam.gserviceaccount.com" \
  --role="roles/storage.objectUser"

gcloud iam service-accounts add-iam-policy-binding \
  attachments@my-project.iam.gserviceaccount.com \
  --member="serviceAccount:attachments@my-project.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountTokenCreator"

The upload and download code uses V4 signed URLs:

import { Storage } from "@google-cloud/storage";

const bucket = new Storage().bucket(process.env.ATTACHMENTS_BUCKET!);

export async function uploadUrl(key: string, contentType: string) {
  const [url] = await bucket.file(key).getSignedUrl({
    version: "v4",
    action: "write",
    expires: Date.now() + 15 * 60 * 1000,
    contentType,
  });
  return url;
}

export async function saveSmallFile(key: string, data: Buffer, contentType: string) {
  await bucket.file(key).save(data, { contentType });
}

export async function downloadUrl(key: string) {
  const [url] = await bucket.file(key).getSignedUrl({
    version: "v4",
    action: "read",
    expires: Date.now() + 5 * 60 * 1000,
  });
  return url;
}

On Cloud Run, getSignedUrl has no private key to sign with, so the library calls the IAM signBlob API. That only works once the service account holds the Service Account Token Creator role on itself, as described in Google's signing guide. It is the most common reason the code works locally with a key file and fails after deploy.

Good to know

Browser uploads to a signed URL are cross-origin requests, so the bucket's CORS configuration has to allow PUT from your web origin. With a V4 signed URL that includes contentType, the browser must send the same Content-Type header, or Cloud Storage rejects the signature.

How to choose

Pick Encore when you want buckets, signed URLs and service permissions created in your own GCP project from the code, with uploads testable locally under encore run and the same code able to deploy to S3 on AWS.

Pick @google-cloud/storage directly when the bucket already exists and is shared with other systems, or when you need features such as resumable uploads and object lifecycle rules configured from the application.

Related guides

• How to add file uploads to a TypeScript API
• How to use Google Cloud Pub/Sub with Node.js
• How to connect Cloud Run to Cloud SQL
• Zero to GCP with TypeScript