starter-monorepo

• starter-monorepo
  • Overview
  • What's inside?
    • Overview of the tech
    • Highlight Features / Components
      • AI / LLM Chat
    • Apps and Libraries
      • frontend: a Nuxt 4 app.
      • backend: a Hono🔥 app.
      • backend-convex: a Convex app.
    • Local packages
    • Utilities
    • Build
    • Develop
      • Wrangler / Cloudflare Workers (Local dev via workerd)
        • API-only setup workerd for Workers bindings:
        • Full setup (everything behaves like workerd) for 100% Cloudflare workerd runtime testing:
      • IMPORTANT:
    • Deploy
    • Notes
      • import ordering
      • Dev with SSL
    • Turborepo Remote Caching
  • Useful Links
    • Turborepo
    • grammY

Overview

This is an opinionated, heavily tweaked monorepo starter template to kick-start a project, whether its a fullstack project, monorepo of multiple libraries and applications, or even just one API server and its related infrastructure deployment and utilities.

Out-of-the-box with the included apps, we have a fullstack project: with a frontend Nuxt 4 app, a main backend using Hono, and a backend-convex Convex app.

• General APIs, such as authentication, are handled by the main backend, which is designed to be serverless-compatible and can be deployed anywhere, allowing for the best possible latency, performance, and cost, according to your needs.
• backend-convex is an optional, modular/add-in backend, utilized to power components like AI Chat.

It is recommended to use an AI Agent (Roo Code recommended) to help you setup the monorepo according to your needs, see Utilities

What's inside?

Overview of the tech

⏩ This template is powered by Turborepo.

😊 Out-of-the-box, this repo is configured for an SSG frontend Nuxt app, and a backend Hono app that will be the main API, to optimize on cost and simplicity.

• You can change the apps/frontend's build script to nuxt build to enable SSR bundle, but some features like authentication will require manual upgrade by you.

🌩️ SST Ion, an Infrastructure-as-Code solution, with powerful Live development.

• SST is 100% opt-in, by using sst CLI commands yourself, like sst dev,
  simply remove sst dependency and sst.config.ts if you want to use another solution.
• currently only backend app is configured, which will deploy a Lambda with Function URL enabled

🔐 Comes with authentication boilerplate via WorkOS AuthKit, see: /apps/backend/api/auth

• Add your env variables, DONE!
• Please note that by default backend comes with a cookies-based session manager, which have great DX, security and does not require an external database (which also means great performance), but as the backend is decoupled with the Nuxt's SSR server, it will not work well with SSR (the session/auth state is not shared).
  So, if you use SSR, you should implement another auth solution.
  • If you have a good session manager implementation, a PR is greatly appreciated!

💯 JS is always TypeScript where possible.

Highlight Features / Components

AI / LLM Chat

Done as an application for T3 Chat Cloneathon competition in 1 week, with no prior AI SDK and chat streams experience, but I think I did an amazing job 🫡!

The focus of the project is for broad, easy personal self-host and family/friends group-use adoption, prioritizing easy-to-access UI/UX.

A simple & friendly LLM Chat system, but still packing some powers, featuring:

• hosted provider that you can control the billing of.
• Supports other add-in BYOK providers, like OpenAI, OpenRouter,...
• Seamless authentication integration with the main backend.
• Beautiful syntax highlighting 🌈.
• Thread branching, freezing, and sharing.
• Real-time, multi-agents, multi-users support ¹.
  • Invite your families and friends, and play with the Agents together in real-time.
  • Or maybe invite your colleagues, and brainstorm together with the help and power of AI.
• Resumable and multi-streams ¹.
  • Ask follow-up questions while the previous isn't done, the model is able to pick up what's available currently 🍳🍳.
  • Multi-users can send messages at the same time 😲😲.
• Easy and private: guest, anonymous usage supported.
  • Your dad can just join and chat with just a link share 😉, no setup needed.
• Mobile-friendly.
• Fast ⚡ with local caching and optimistic updates.

*1: currently the "stream" received when resuming or for other real-time users in the same thread is implemented via a polling, not SSE. it is intentionally chosed to be this way for more minimal infrastructure setup and wider hosting support, so smaller user groups can host their own version easily, it is still very performant and efficient.

• There is boilerplate code for SSE resume support, you can simply add a pub-sub to the backend and switch to using SSE resume in ChatInterface component.

Apps and Libraries

frontend: a Nuxt 4 app.

• By default, the frontend /api/* routes is proxied to the backendUrl.
• The rpcApi plugin will call the /api/* proxy if they're on the same domain but different ports (e.g: 127.0.0.1)

  • this mimics a production environment where the static frontend and the backend lives on the same domain at /api, which is the most efficient configuration for Cloudfront + Lambda Function Url, or Cloudflare Workers.

  • If the frontend and backend are on different domains then the backend will be called directly without proxy.
  • This could be configured in frontend's app.config.ts

backend: a Hono🔥 app.

backend-convex: a Convex app.

Local packages

• @local/locales: a shared central locales/i18n data library powered by spreadsheet-i18n.
  • 🌐✨🤖 AUTOMATIC localization with AI, powered by lingo.dev, just pnpm run i18n.
  • 🔄️ Hot-reload and automatic-reload supported, changes are reflected in apps (frontend, backend) instantly.
• @local/common: a shared library that can contain constants, functions, types.
• @local/common-vue: a shared library that can contain components, constants, functions, types for vue-based apps.
• tsconfig: tsconfig.jsons used throughout the monorepo.

Utilities

This Turborepo has some additional tools already setup for you:

• 🧐 ESLint + stylistic formatting rules (antfu)
• 📦📢 repo-release script, easily generates changelog, bump version, create GitHub release, and publish your packages to npm.
• 📚 A few more goodies like:
  • lint-staged pre-commit hook
  • 🤖 Initialization prompt for AI Agents to modify the monorepo according to your needs.
    • To start, open the chat with your AI Agent, and include the INIT_PROMPT.md file in your prompt.

Build

To build all apps and packages, run the following command:
pnpm run build

Develop

If you just want a quick check out, without having to set up anything, you can use pnpm run dev:noConvex, this will skips backend-convex, which is the only component that have initial set ups, though, this of course means related features are disabled (AI Chat).

To develop all apps and packages, run the following command:
pnpm run dev

By default, the access URL is set to: 127.0.0.1:3300

For local development environment variables / secrets, create a copy of .env.dev to .env.dev.local.

Wrangler / Cloudflare Workers (Local dev via workerd)

API-only setup workerd for Workers bindings:

• Initial one-time setup:
  • Config enviroment variables and secrets for wrangler (refer to Cloudflare's docs).
  • Config frontend/.env.dev.local: set NUXT_PUBLIC_BACKEND_URL=https://127.0.0.1:3310
  • Run mkdir -p apps/frontend/.output/public so that wrangler does not error about assets folder not found
• Run pnpm dlx wrangler dev in one terminal, and pnpm run dev in another terminal, you can develop with HMR just like normal! (127.0.0.1:3300).

Full setup (everything behaves like workerd) for 100% Cloudflare workerd runtime testing:

• Initial one-time setup:
  • Config enviroment variables and secrets for wrangler (refer to Cloudflare's docs).
  • (Optional) Config apps/frontend/.env.workerd.dev if you use convex or use different ip/port.
• When your frontend change, manually build a new static dist:
  • Start the local backend server
  • Run build:workerdLocal script for frontend to generate SSG assets
  • Close the backend server
• (Optional) Run the convex dev server if you use convex.
• Run pnpm dlx wrangler dev to start wrangler dev server, and you can connect via 127.0.0.1:3310.
  • workerd does not work with Alpine Linux, so if you use the included Dev Container, change the base image to some other distro.

IMPORTANT:

For the best development experience, for VSCode and its forks, you should use the workspace's TypeScript version instead of VSCode's shipped version, to do this, open any file with TypeScript support like .ts, .vue, then, from the IDE's command palette, run the "TypeScript: Select TypeScript Version" and choose "Use Workspace Version".

Deploy

• You can add your custom deploy instructions in deploy script and scripts/deploy.sh in each app, it could be a full script that deploys to a platform, or necessary actions before for some platform integration deploys it, frontend will only start build and deploy after all backends are deployed, to have context for SSG.
• The repo also contains some deployment presets samples:
  • GitHub Action to deploy frontend to GitHub Pages
  • Wrangler configured to deploy fullstack to Cloudflare, just run npx wrangler deploy or connect and deploy it through the Cloudflare Dashboard.
    • Wrangler will deploy backend and frontend at the same time, which might cause frontend to have old context for SSG, you should trigger a redeploy in such case.
  • Deploy backend to Lambda via SST

• Some more deploying notes:
  • backend-convex is disabled by default, to enable:
    • rename _deploy script to deploy in backend-convex/package.json
    • Run the deploy script once manually to get Convex's production url, set it to NUXT_PUBLIC_CONVEX_URL in frontend/.env.prod or CI / build machine env var.

Notes

import ordering

Imports should not be separated by empty lines, and should be sorted automatically by eslint.

Dev with SSL

The project comes with a localcert SSL at locals/common/dev to enable HTTPS for local development (because some 3rd-party services require local dev to have HTTPS, so I enable it by default), generated with mkcert, you can install mkcert, generate your own certificate and replace it, or install the localcert.crt to your trusted CA to remove the untrusted SSL warning.

Turborepo Remote Caching

Turborepo can use a technique known as Remote Caching to share cache artifacts across machines, enabling you to share build caches with your team and CI/CD pipelines.

By default, Turborepo will cache locally. To enable Remote Caching you will need an account with Vercel. If you don't have an account you can create one, then enter the following commands:

npx turbo login

This will authenticate the Turborepo CLI with your Vercel account.

Next, you can link your Turborepo to your Remote Cache by running the following command from the root of your Turborepo:

npx turbo link

Useful Links

Learn more about the tech of the repo:

Turborepo

• Tasks
• Caching
• Remote Caching
• Filtering
• Configuration Options
• CLI Usage

grammY

https://grammy.dev