Skip to content
Public template

About

Vite+ (vp) TanStack Start monorepo with shadcn/ui, Paraglide.js (i18n), Hono, oRPC, drizzle-orm, better-auth, Feature-Sliced Design (FSD), and more. Dockerized and opinionated.

Topics

Resources

Contributing

Security policy

Stars

133 stars

Watchers

2 watching

Forks

Repository files navigation

NodeJS version badge License badge Last commit badge GitHub stars badge GitHub forks badge GitHub issues badge GitHub pull requests badge Repo views badge

Vite Plus (Vite+) TanStack Start monorepo with shadcn/ui, Paraglide.js (i18n), Hono, oRPC, drizzle-orm, better-auth, Feature-Sliced Design (FSD), and more. 🐋 Dockerized and opinionated. Compatible with the ⛅ Cloudflare Workers workerd runtime with a few tweaks.

tsu!stack Screenshot

✨ Live Demo Deployments ✨
Dockerfile (Coolify)
Docker Compose (Coolify)
Merged Web + Server with Dockerfile (Coolify) | see branch
Merged Web + Server (Cloudflare Workers) | see branch

Table of Contents

Getting Started

Prerequisites

  • Node.js ≥ 26
  • Vite Plus (vp)
    • install via curl -fsSL https://vite.plus | bash (macOS/Linux) or irm https://vite.plus/ps1 | iex (Windows)
  • pnpm ≥ 12
    • install via vp install -g pnpm
  • Docker

Setup

Use the dedicated CLI Tool and answer the setup wizard questions:

npm create tsu-stack@next my-app
cd my-app
vp run dev

Keeping Template Changes

Projects created from this template include the sync-template agent skill. Ask your coding agent to use $sync-template when you want to compare or integrate updates from the matching tsu-stack branch. The generated .tsu-stack.jsonc file records the exact source commit used at creation time.

Running PostgreSQL Variants with Docker Locally

As an alternative to vp run dev, you can run the full stack inside Docker using the local compose file:

cp .env.docker.example .env.docker # And set environment variables as needed
vp run docker:up
vp run docker:up:build # OR: force a rebuild when you make changes to the code

Database Migrations

# for PostgreSQL-based variants
vp run db:migrate        # uses the database specified in packages/db/drizzle.config.ts

# for Cloudflare-based variants
vp run db:migrate:local  # for the local miniflare D1 database
vp run db:migrate:remote # for the remote/prod D1 database

Tech Stack

Here is a non-exhaustive list of the main technologies used in this project, along with their purposes and possible alternatives they replace:

Technology Purpose Replaces/Similar Alternatives
pnpm Fast, disk-efficient package manager for Node.js with package catalogs for monorepo dependecy deduplication. npm, yarn
Vite Plus (Vite+) Unified toolchain for development, testing, and building the monorepo. Turborepo, Nx, Vitest, Prettier, ESLint, husky, lint-staged, lefthook, tsdown, tsc
TanStack Start Modern full-stack React framework with support for SPA, SSR, ISR, and integrated with TanStack Query. It uses Vite's Nitro adapter for cross-platform deployment portability. Next.js, Remix, React Router
Paraglide.js Compiled internationalization (i18n) library for managing translations. i18next, next-intl
Hono Lightweight web server framework built on web standards and is WinterCG-compliant for cross-platform portability. Express.js, Fastify, Elysia.js
oRPC RPC framework to define API routes and generate OpenAPI specs and documentation with Scalar. tRPC
Drizzle ORM Type-safe and lightweight ORM for database interactions. Prisma, TypeORM
PostgreSQL Stable open-source relational database. MySQL, MariaDB
Better Auth Self-hosted authentication framework with support for all major OAuth providers. Auth.js
Docker Containerization for local development and deployment. Podman
shadcn/ui Accessible and customizable React component library. Chakra UI, Material UI, Mantine UI

Deployment

This project is designed to be deployed as separate applications for the server and web frontend. Below are the recommended deployment strategies and configurations.

Coolify

Coolify can be used to deploy the server and web applications. Choose a strategy and follow the steps below to configure each app:

Option 1: Separate Dockerfiles

Warning

This approach retains rolling updates in Coolify and has minimal downtime, but it is harder to scale compared to Docker Compose.

Server Deployment
  1. Base Directory: /.
  2. Dockerfile Location: /apps/server/Dockerfile.
  3. Domain: Assign a domain, e.g., https://example.com/server.
  4. Port: Expose port 5000.
Web Deployment
  1. Base Directory: /.
  2. Dockerfile Location: /apps/web/Dockerfile.
  3. Domain: Assign a domain, e.g., https://example.com/web.
  4. Port: Expose port 3000.

Caution

Ensure that the Strip Prefixes option is unchecked in the Advanced settings to avoid issues with custom base paths.

Finally, set any required environment variables in the "Environment Variables" tab for each application and press the "Deploy" button to start the deployment process.

Option 2: Docker Compose

  1. When creating a new application in Coolify, select "Private Repository (with GitHub App)" and select your repository with your tsu-stack app.
  2. Next, change the "Build Pack" to "Docker Compose" and set the "Docker Compose Location" to /docker-compose.coolify.yaml.
  3. Refer to Server Deployment and Web Deployment sections above for domain configurations.
  • you need to explicitly bind the port in the domain since Docker Compose doesn't have Expose Port, for example: https://example.com:3000/web for the web app and https://example.com:5000/server for the server.
  1. Set any required environment variables in the "Environment Variables" tab.
  2. Press the "Deploy" button to start the deployment process.

Caution

Ensure that the Strip Prefixes option is unchecked in the Advanced settings to avoid issues with custom base paths.

Cloudflare Workers

Tip

You can clone the variant/merged-cloudflare branch for a Cloudflare Workers-compatible setup.

You will need to use the @cloudflare/vite-plugin adapter instead of nitro. See this commit for example changes.

Then, you will need to switch to using a singleton db instance instead of a connection pool in the server app since Cloudflare Workers do not support long-lived connections. See this commit for example changes.

You'll need to set the secrets manually in the Cloudflare dashboard before running the deployment commands or via pnpm wrangler secret put <VARIABLE_NAME> one-by-one.

Finally, you can deploy by running the following commands:

pnpm wrangler login # authenticate with your Cloudflare account # copy the shared env variables to the web app's env file for wrangler to read them
vp run deploy       # run the deploy task which uses wrangler to deploy the web app to Cloudflare Workers

Caution

I do not recommend this way of deploying because it is prone to human error.

Git-based CI/CD

You can take advantage of Cloudflare's Git-based CI/CD by connecting your GitHub repository to your Cloudflare account and configuring the deployment settings to automatically deploy on pushes to your main branch.

You will need to set up the build environment variables and variables and secrets manually in the Cloudflare dashboard in order for builds to succeed.

Build Settings Secrets & Variables (Runtime)
Build Settings Secrets & Variables

Caution

There isn't an automatic way to do this with my current setup. So you'll need to link the repository first and trigger a failed build, then set the variables and trigger another deployment for the changes to take effect.

Tip

You don't need DATABASE_URL if you opt-in to the cloudflare-d1 variant and enable automatic Cloudflare D1 provisioning.

Dokploy

Dokploy can deploy the server and web applications using the included Dockerfiles.

  1. Create two applications connected to your repository, one for the server and one for the web app.

  2. Select the Dockerfile build type for each application and configure:

    Setting Server Web
    Dockerfile Path apps/server/Dockerfile apps/web/Dockerfile
    Docker Context Path . (repository root) . (repository root)
    Docker Build Stage production production
  3. In each application's Environment tab, populate Build Time Arguments with the ARG values declared in its Dockerfile. Both applications require VITE_SERVER_URL, VITE_WEB_URL, DATABASE_URL, and BETTER_AUTH_SECRET. For the web app, also set VITE_IMGPROXY_URL and VITE_IMGPROXY_SIGNATURE if using imgproxy. See Environment Variables for their meanings.

  4. Configure the required runtime Environment Variables in the same tab as well. Build arguments do not automatically populate the final runtime container.

  5. Assign domains matching VITE_SERVER_URL and VITE_WEB_URL, routing to container ports 5000 for the server and 3000 for the web app. Save the settings and deploy both applications.

Important

Setting only runtime environment variables is not enough: the web build also needs them. Local .env files are excluded from the Docker build context, so provide build-time values through Dokploy and rebuild after changing them.

Caution

The included Dockerfiles consume build arguments, not Dokploy's Build-time Secrets. Build arguments can be exposed in build metadata or cache; use non-sensitive build-only values where possible and configure real credentials at runtime. To pass sensitive values during the build, adapt the Dockerfiles to consume secret mounts first. See Dokploy's environment variables for Dockerfile builds.

Deploying to Other Platforms

TanStack Start uses Nitro as its server engine, which means the web app can be deployed to any platform Nitro supports out of the box - Cloudflare Workers, Vercel, AWS Lambda, Deno Deploy, and many more. Configure the target by setting the appropriate Nitro preset in apps/web/vite.config.ts.

Caution

The server (apps/server) is a Node.js/Hono server and is not compatible with edge runtimes like Cloudflare Workers. It must be deployed to a Node.js-capable environment (e.g. a VPS, container, or serverless platform with Node.js support). This is by design - the dedicated Node.js server is cheaper to self-host for database-heavy workloads.

Environment Variables

Server

For the Hono server, use the following environment variables:

Variable Name Required Default Value Description
VITE_SERVER_URL ✅ - Base URL for the server. May also include a subpath if needed, ex: https://example.com/server.
VITE_WEB_URL ✅ - Base URL for the web app. May also include a subpath if needed, ex: https://example.com/web.
BETTER_AUTH_SECRET ✅ - Secret key for Better-Auth. Generate with vp run auth:secret.
BETTER_AUTH_TRUSTED_PROXIES ❌ - Comma-separated IP addresses or CIDR ranges for proxies allowed to append the client X-Forwarded-For chain.
DATABASE_URL ✅ - PostgreSQL connection string (not required using cloudflare-d1 variant).
ENABLE_OPEN_API_DOCS ❌ false Enable OpenAPI /docs endpoint.

Web

For the web app, use the following environment variables:

Variable Name Required Default Value Description
VITE_SERVER_URL ✅ - Base URL for the server. May also include a subpath if needed, ex: https://example.com/server.
VITE_WEB_URL ✅ - Base URL for the web app. May also include a subpath if needed, ex: https://example.com/web.
BETTER_AUTH_SECRET ✅ - Secret key for Better-Auth. Generate with vp run auth:secret.
DATABASE_URL ✅ - PostgreSQL connection string (not required using cloudflare-d1 variant).
VITE_IMGPROXY_URL ❌ - URL for image optimization. You'll need to deploy your own imgproxy container first.
VITE_IMGPROXY_SIGNATURE ❌ _ imgproxy signature path segment. Use insecure or a precomputed signature if your imgproxy setup requires it.

Merging Server to Web App

Tip

An example can be found in the variant/merged branch. You can check this commit to see the changes needed.

Since Hono is built on web standards, you can mount the Hono App into the TanStack Start web server.

// apps/web/package.json
"dependencies": {
  // ...
  "@tsu-stack/i18n": "workspace:*",
  "@tsu-stack/server": "workspace:*", // add this to import the server app into the web app
  "@tsu-stack/ui": "workspace:*",
  // ...
}

Then we can import our app from the server package.

// apps/web/src/routes/server/$.ts
import { createFileRoute } from "@tanstack/react-router";

import { app } from "@tsu-stack/server";

export const Route = createFileRoute("/server/$")({
  server: {
    handlers: {
      GET: ({ request }) => {
        return app.fetch(request);
      },

      POST: ({ request }) => {
        return app.fetch(request);
      }
    }
  }
});

Then merge your web environment variables with the server ones and make sure VITE_SERVER_URL points to the web domain's subpath.

-VITE_SERVER_URL=http://localhost:5000/server
+VITE_SERVER_URL=http://localhost:3000/web/server
VITE_WEB_URL=http://localhost:3000/web

You will also need to adjust the getConnInfo import to match your runtime environment.

-import { getConnInfo } from '@hono/node-server/conninfo'
+import { getConnInfo } from 'hono/vercel'

Warning

hono/vercel works in any environment, but it may not have all the information needed for the logger middleware.

Then lastly, remove the serve() call in apps/server/src/index.ts since the Hono app is now being served by the TanStack Start server.

-import { serve } from "@hono/node-server";

void (async () => {
  await migrateDatabase()

-  serve(
-    {
-      fetch: app.fetch,
-      port: 5000,
-    },
-    (info) => {
-      logger.info(`Server is running on http://localhost:${info.port}${new URL(apiEnvServer.VITE_SERVER_URL).pathname}`)
-    },
-  )
})()

Warning

You may want to refactor the logging middlewares since the TanStack Start server also logs incoming/outgoing requests, similar to the Hono app's middleware.

Warning

You may also need to adjust your Docker Compose file and the apps/web/Dockerfile to include build args needed in the server app such as DATABASE_URL and handle other environment variables.

Resource Usage

When mounting the Hono app into the TanStack Start web server, you will save the resources of running a separate Node.js server.

But keep in mind that all API requests will now consume resources from the web server container, leading to the web server being less responsive under heavy API load.

However, the benefit is singular deployments and lower memory usage for websites that don't receive much traffic (around 70MB with a single app vs 130MB when separated on idle).

Note

I personally keep them separated so that when it's time to scale, I can scale the web server independently or deploy it to another platform like Cloudflare Workers for serverless edge performance.

Issue Watchlist

Last verified on November 10, 2026.

  • TanStack Router #7529 - Keep the Router/Start dependency set pinned because newer router-core releases can leave the SSR query stream open until the serialization timeout.
  • TanStack Router #6275 - Keep the Vite preview host on 127.0.0.1 so Docker prerender builds can reach the preview server.
  • TanStack Router #8550 - A CSP nonce delivered in a response header can make hydration duplicate inline module scripts because the browser hides the nonce from getAttribute().
  • TanStack Router #8789 - Hydration scripts can miss a CSP nonce when it is assigned after the router's SSR state is created.

Pitfalls

  • Prefer exposing the web app and API on one public origin, such as https://example.com and https://example.com/server. Host-only auth cookies then reach authenticated SSR without being shared with sibling subdomains. Different-site auth can also fail in Safari because WebKit's Intelligent Tracking Prevention (ITP) applies Full Third-Party Cookie Blocking. If separate public origins are unavoidable, test authenticated SSR and OAuth in Safari and configure Better Auth cookies, trusted origins, CORS, and proxy routing deliberately; sibling subdomains are same-site for ITP but still do not share host-only cookies.
  • The template does not enforce CSP because the TanStack nonce issues in the watchlist can break hydration. Treat all user-authored HTML as untrusted and sanitize it before rendering. Revisit a strict nonce- or hash-based CSP before adding high-risk script integrations; do not silence CSP errors with unsafe-inline as a permanent fix.
  • If you change the API's /server path or put web and API on different origins, update VITE_SERVER_URL, proxy routing, CORS origins, and OPTIONS forwarding to match.
  • For per-client rate limits behind a proxy, set BETTER_AUTH_TRUSTED_PROXIES to only the proxy IP addresses or CIDR ranges that append X-Forwarded-For. Leave it empty for direct connections. If the list is too broad, clients in that range can spoof forwarded addresses and bypass limits; if the actual proxy is omitted, all traffic is grouped under the proxy address.
  • If you deploy to production, replace the example BETTER_AUTH_SECRET with a generated secret shared by the web app and API. If you publish Cloudflare build artifacts outside Wrangler, exclude dist/<worker>/.dev.vars, which can contain build secrets.
  • If the web app runs under a subpath such as /web and you want search engines to discover robots.txt, expose it at the domain root through a redirect or root route. For multiple subpath apps, add a root sitemap index and point __root.tsx at it if you want the app to advertise that index.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. If there are any bugs, please open an issue.

To get started, fork the repo, make your changes, add, commit, and push your changes to your fork. Then, open a pull request. If you're new to GitHub, this tutorial might help.

You can support the project by giving it a star, sharing it with your friends, contributing to the project, and reporting any bugs you find.

Acknowledgements

This repository builds on mugnavo/cove-monorepo.

License

This project is licensed under the MIT License - see the LICENSE file for details.

About

Vite+ (vp) TanStack Start monorepo with shadcn/ui, Paraglide.js (i18n), Hono, oRPC, drizzle-orm, better-auth, Feature-Sliced Design (FSD), and more. Dockerized and opinionated.

Topics

Resources

Contributing

Security policy

Stars

133 stars

Watchers

2 watching

Forks

Sponsor this project

Used by

Contributors

Languages