AWS Amplify TanStack Start Adapter

This package contains the AWS Amplify TanStack Start Adapter.

Install

npm add aws-amplify amplify-adapter-tanstack-start

Usage

Configure Amplify in TanStack Start

Configure Amplify for server-side usage

You will need to create a runWithAmplifyServerContext function to use Amplify APIs on the server-side of your TanStack Start app.

You can create an amplifyServerUtils.ts file under a lib folder in your codebase. In this file, you will import the Amplify backend outputs from the amplify_outputs.json file that is generated by Amplify, and use the createServerRunner function to create the runWithAmplifyServerContext function.

For example, the lib/amplifyServerUtils.ts file may contain the following content:

import { createServerRunner } from "amplify-adapter-tanstack-start";
import outputs from "../amplify_outputs.json";

export const { runWithAmplifyServerContext } = createServerRunner({
  config: outputs,
});

Generate the Data client for TanStack Start server runtimes

You can create an amplify-ssr-client.ts file under a lib folder in your codebase. In this file, you will import the Amplify backend outputs and use the generateClient function imported from aws-amplify/api/server module to create the data client.

For example, the lib/amplify-ssr-client.ts file may contain the following content:

import type { Schema } from "amplify/data/resource";
import { parseAmplifyConfig } from "aws-amplify/utils";
import { generateClient } from "aws-amplify/api/server";
import config from "../amplify_outputs.json";

const amplifyConfig = parseAmplifyConfig(config);
export const client = generateClient<Schema>({
  config: amplifyConfig,
});

Configure Amplify for client-side usage

When you use the Amplify library on the client-side of your TanStack Start app, you will need to configure Amplify by calling Amplify.configure as you would in a single-page application.

Note: You will need to set ssr to true when calling Amplify.configure. This instructs the Amplify library to store tokens in the cookie store of a browser. Cookies will be sent along with requests to your TanStack Start server for authentication.

import outputs from "../amplify_outputs.json";
import { Amplify } from "aws-amplify";

Amplify.configure(outputs, {
  ssr: true, // required when using Amplify with TanStack Start SSR
});

Calling Amplify category APIs on the server side

In TanStack Start, server-side Amplify API calls must be made inside a createServerFn handler, where the request context is automatically managed by the TanStack Start runtime.

Create a server function using createServerFn and call runWithAmplifyServerContext inside the handler:

// app/routes/index.tsx
import { createFileRoute } from "@tanstack/react-router";
import { createServerFn } from "@tanstack/start";
import { runWithAmplifyServerContext } from "~/lib/amplifyServerUtils";
import { client } from "~/lib/amplify-ssr-client";

const fetchTodos = createServerFn().handler(async () => {
  const { data: todos, errors } = await runWithAmplifyServerContext({
    operation: (contextSpec) => client.models.Todo.list(contextSpec),
  });
  return {
    todos,
    error: errors?.map((e) => e.message).join(", "),
  };
});

export const Route = createFileRoute("/")({
  loader: () => fetchTodos(),
  component: Home,
});

function Home() {
  const { todos } = Route.useLoaderData();
  return (
    <div>
      <h1>Todo List</h1>
      <ul>
        {todos?.map((todo) => (
          <li key={todo.id}>{todo.content}</li>
        ))}
      </ul>
    </div>
  );
}