Hosting TanStack Start SSR on AWS with AWS Blocks

AWS Blocks  is an AWS toolkit that lets you define your backend and infrastructure together in TypeScript. When I moved a personal side project to AWS Blocks, I found that the TanStack Start  SSR frontend I was using could be hosted on CloudFront + Lambda as well. The catch is that the documentation focuses on Next.js and SPA frontends, so getting TanStack Start running takes a little extra work. In this article I'll walk through the key points, using a minimal working example.

The full source code is here:

AWS Blocks is a toolkit where you compose your backend from parts called Building Blocks: authentication, key-value stores, tables, file buckets, and so on. What stands out is the development experience. npm run dev runs every Block as a local mock, so you can develop without an AWS account. When you deploy, the same code switches over to the real services like DynamoDB and Lambda.

You can scaffold a project with create-blocks-app:

My example starts from this react template (a Vite + React SPA) and swaps the frontend for TanStack Start. The backend is as small as it gets: no auth, no database, just one API method.

On the frontend, import { api } from 'aws-blocks' gives you a fully typed client for this API. There are no HTTP endpoints to configure and no client code to generate.

Here is what a deployment looks like. CloudFront routes each request by path: static assets go to S3, SSR goes to a Lambda function running the Nitro  build, and API calls go to the Blocks API Lambda. Both the SSR and API Lambdas sit behind their own API Gateway (REST API).

Three things make TanStack Start work in this setup.

Current versions of TanStack Start don't bundle Nitro. Nitro is a full-stack server framework compatible with any runtime and any deployment target; at build time you pick a preset and it emits a server bundle tailored to where you're deploying. vite build alone produces a server bundle, but not an entry point that runs on Lambda. Adding the nitro Vite plugin fixes that by generating an .output/ directory that includes a Lambda handler.

Two details matter here.

First, the nitro plugin is only enabled when command === 'build'. Enabling it in the dev server conflicts with TanStack Start's own SSR and breaks things. In dev, TanStack Start handles SSR by itself, so nitro is only needed for production builds.

Second, awsLambda: { streaming: true } is required. The AWS Blocks Hosting construct serves SSR through API Gateway (REST API) response streaming, so a buffered handler gets you 502s from CloudFront. I lost some time on this one.

On the CDK side, all you change in the template-generated aws-blocks/index.cdk.ts is the Hosting construct. The diff from the SPA template is two lines:

The documentation lists the framework option as 'spa' | 'static' | 'nextjs', but the implementation ships a nitro adapter alongside Nuxt and Astro ones, and 'nitro' is accepted. Nitro's .output/ format is the same one Nuxt uses, so any framework that can produce it — TanStack Start included — can be hosted this way.

Passing api: blocksStack makes CloudFront proxy the /aws-blocks/api path to the backend Lambda, so the frontend and backend share one origin. No CORS configuration needed.

A TanStack Start route loader runs on the server (the SSR Lambda) for the initial request, and in the browser for client-side navigation afterwards. The AWS Blocks client works the same way in both environments, so the loader is just:

This works because the client resolves the API URL differently per environment. In the SSR Lambda, the Hosting construct automatically injects a BLOCKS_API_URL environment variable (the API Gateway endpoint of the Blocks API), and the client reads it. In the browser, the client fetches a config file from the hosting origin (/.blocks-sandbox/config.json) and calls the API through the CloudFront proxy. None of this is visible in your application code.

My example has no authentication, so calling the API from the loader is all there is to it. If you need to call an authenticated API during SSR, use withAuth (from @aws-blocks/blocks/server) to forward the browser's cookies to the API call. Cookie auto-detection is built in for Next.js and Nuxt, but TanStack Start isn't covered, so pull the cookie out of the request headers and pass it as the second argument:

Deployment is a single script that comes with the template. It builds, synthesizes, and deploys in one go:

When it finishes, it prints the CloudFront URL. The page shows the loader result, but the reliable way to confirm SSR is to view the page source:

The API response is right there in the HTML — rendered by the SSR Lambda calling the Blocks API before any JavaScript reaches the browser. The page also has a button that re-fetches the same API from the browser, so you can see the same api.getServerInfo() call working on both sides.

I hit one bug in AWS Blocks worth writing down. The config.json that browsers use to resolve the API URL is first uploaded as a build-time placeholder and then overwritten with the real values during deployment. But the CloudFront cache key is internally rewritten to live under /builds/<buildId>/, so the post-deploy cache invalidation (/.blocks-sandbox/*) never matches it — and the placeholder can stay cached for up to a year. In that state, every API call from the browser fails.

The example works around it with patch-package, widening the invalidation path to /* (see the patches/ directory). It's applied automatically on npm install, so you don't have to think about it. I've also submitted a fix upstream ; once it's merged, the patch won't be needed.

Because the AWS Blocks Hosting construct ships a nitro adapter, any framework that can emit Nitro's .output/ can be hosted — even ones that aren't on the officially supported list. For TanStack Start, the only changes needed were adding the nitro plugin to vite.config.ts and setting framework: 'nitro' on the Hosting construct.

All the code is in the example repository. npm run dev runs on local mocks, so you can try it without an AWS account: