{post.title}
{post.excerpt}
No active organization
;
}
return
{messages.map((message) => {
const text = message.parts
.filter((part) => part.type === 'text')
.map((part) => part.text)
.join('');
return (
);
}
```
## Conversation History
Chats are stored in the database and can be retrieved via tRPC:
```typescript filename="trpc/routers/organization/organization-ai-router.ts" lineNumbers
import { createTRPCRouter, protectedOrganizationProcedure } from '@/trpc/init';
import { TRPCError } from '@trpc/server';
import { and, desc, eq, sql } from 'drizzle-orm';
import { z } from 'zod';
import { appConfig } from '@/config/app.config';
import { db } from '@/lib/db';
import { aiChatTable } from '@/lib/db/schema';
export const organizationAiRouter = createTRPCRouter({
listChats: protectedOrganizationProcedure
.input(
z
.object({
limit: z
.number()
.min(1)
.max(appConfig.pagination.maxLimit)
.optional()
.default(appConfig.pagination.defaultLimit),
offset: z.number().min(0).optional().default(0)
})
.optional()
)
.query(async ({ ctx, input }) => {
// Use SQL builder to select only needed columns and extract first message
const chats = await db
.select({
id: aiChatTable.id,
title: aiChatTable.title,
pinned: aiChatTable.pinned,
createdAt: aiChatTable.createdAt,
firstMessageContent: sql
{message.role}:{' '}
{message.role === 'assistant' ? (
{text}
) : (
{text}
)}
);
})}
OPENAI_API_KEY must contain a secret key created in the OpenAI
Platform. OpenAI keys commonly begin with sk-. A value beginning
with pk_test_ is a Stripe publishable test key and cannot
authenticate an OpenAI request. Keep the OpenAI key server-only and never add
a NEXT_PUBLIC_ prefix.
NEXT_PUBLIC_ variable.
twoFactorEnabled, banned,{' '}
banReason and onboardingComplete are marked with{' '}
input: false. Do not expose them through the generic client user
update API. Change them through an authenticated server procedure or the
corresponding Better Auth endpoint.
My protected page
;
}
```
### For specific roles
More interesting is to check if the user has the necessary permissions to access the page. For example, you can make a page only accessible for users with the `admin` role.
```tsx filename="app/admin/page.tsx" lineNumbers
import { redirect } from 'next/navigation';
import { getSession } from '@/lib/auth/server';
export default async function MyAdminPage() {
const session = await getSession();
if (session?.user.role !== 'admin') {
return redirect('/app');
}
return This page is only accessible for admins
;
}
```
### For active or specific subscription
Or if you want to check for an active subscription, you can do the following:
```tsx filename="app/premium/page.tsx" lineNumbers
import { redirect } from 'next/navigation';
import { getSession } from '@/lib/auth/server';
import {
getActivePlanForOrganization,
requirePaidPlan,
requireSpecificPlan
} from '@/lib/billing/guards';
export default async function MyPremiumPage() {
const session = await getSession();
if (!session?.activeOrganizationId) {
return redirect('/app');
}
// Check for any paid plan
try {
const { planId } = await requirePaidPlan(session.activeOrganizationId);
// User has a paid plan
} catch {
return redirect('/app');
// or show a message to the user that they need to subscribe to the premium plan
}
// Or check for a specific plan
try {
const { planId } = await requireSpecificPlan(session.activeOrganizationId, [
'pro',
'enterprise'
]);
// User has pro or enterprise plan
} catch {
return (
This page is only accessible for users with a pro subscription
);
}
return (
This page is only accessible for users with an active subscription
);
}
```
### For organization role
You can also check if a user has a specific role inside the current organization. For example, you might want to add features that are only available for organization owners or admins.
```tsx filename="app/[organizationSlug]/settings/page.tsx" lineNumbers
import { redirect } from 'next/navigation';
import { eq } from 'drizzle-orm';
import { getOrganizationById, getSession } from '@/lib/auth/server';
import { db } from '@/lib/db';
import { organizationTable } from '@/lib/db/schema';
export default async function MyOrganizationPage({
params
}: {
params: Promise<{ organizationSlug: string }>;
}) {
const { organizationSlug } = await params;
const session = await getSession();
// First, find organization by slug
const [org] = await db
.select({ id: organizationTable.id })
.from(organizationTable)
.where(eq(organizationTable.slug, organizationSlug))
.limit(1);
if (!org) {
redirect('/app');
}
// Then get full organization with members
const organization = await getOrganizationById(org.id);
if (!organization) {
redirect('/app');
}
const membership = organization.members.find(
(member) => member.userId === session?.user.id
);
if (
!membership ||
(membership.role !== 'admin' && membership.role !== 'owner')
) {
return This page is only accessible for organization admins
;
}
return This page is only accessible for organization admins
;
}
```
## Display UI based on permissions (client side)
On client side, you can use the `authClient.useSession()` hook to get the session and then check if the user has the necessary permissions.
### For authenticated users
```tsx filename="components/protected-component.tsx" lineNumbers
'use client';
import { authClient } from '@/lib/auth/client';
export function MyComponent() {
const { data: session } = authClient.useSession();
if (!session) {
return You need to be logged in to access this page
;
}
return You are logged in
;
}
```
This page is only accessible for admins
;
}
return This page is only accessible for admins
;
}
```
### For active or specific subscription
```tsx filename="components/premium-component.tsx" lineNumbers
'use client';
import { trpc } from '@/trpc/client';
export function MyComponent() {
const { data: subscriptionStatus } =
trpc.organization.subscription.getStatus.useQuery();
if (!subscriptionStatus?.enabled) {
return Billing is not enabled
;
}
if (!subscriptionStatus.activePlan) {
return You don't have an active subscription
;
}
if (
subscriptionStatus.activePlan.planId !== 'pro' &&
subscriptionStatus.activePlan.planId !== 'enterprise'
) {
return You need to subscribe to the pro plan to access this page
;
}
return You have an active subscription
;
}
```
### For organization role
```tsx filename="components/organization-component.tsx" lineNumbers
'use client';
import { authClient } from '@/lib/auth/client';
export function MyComponent() {
const { data: activeOrganization } = authClient.useActiveOrganization();
const { data: session } = authClient.useSession();
if (!activeOrganization || !session) {
return No active organization
;
}
// Find the user's membership in the active organization
const membership = activeOrganization.members.find(
(member) => member.userId === session.user.id
);
// Check if user is admin or owner
const isOrganizationAdmin =
membership && (membership.role === 'admin' || membership.role === 'owner');
if (!isOrganizationAdmin) {
return This page is only accessible for organization admins
;
}
if (membership.role !== 'owner') {
return This page is only accessible for organization owners
;
}
return This page is only accessible for organization admins
;
}
```
---
## User and Session
**URL**: https://www.achromatic.dev/docs/starter-kits/pro-nextjs-drizzle/authentication/sessions
**Description**: Learn how to access the user and session in your application.
## Accessing the user and session
You can access the user and session in your application using the `useSession` hook on the client or `getSession` function on the server.
### Client-side
```tsx filename="components/user-profile.tsx" lineNumbers
'use client';
import { authClient } from '@/lib/auth/client';
export function UserProfile() {
const { data: session, isPending } = authClient.useSession();
if (isPending) return Loading...
;
if (!session) return Not authenticated
;
return (
Hello, {session.user.name}!
Email: {session.user.email}
Not authenticated
;
}
if (isPending) {
return Loading...
;
}
return Hello, {session.user.name}!
;
}
```
## Reload session
If for some reason you need to reload the session, for example when you changed some property of the user like its name or role, you can use the `refetch` function.
```tsx filename="components/reload-session.tsx" lineNumbers
'use client';
import { authClient } from '@/lib/auth/client';
export function MyComponent() {
const { data: session, refetch } = authClient.useSession();
const handleReload = async () => {
await refetch();
};
return (
Hello, {session?.user.name}!
User name: {session.user.name}
;
}
```
### Via tRPC context
In tRPC procedures, the session is automatically available in the context:
```typescript filename="trpc/routers/example.ts" lineNumbers
import { createTRPCRouter, protectedProcedure } from '@/trpc/init';
export const exampleRouter = createTRPCRouter({
getProfile: protectedProcedure.query(async ({ ctx }) => {
// Session is available in ctx.session, user is in ctx.user
const user = ctx.user;
return user;
})
});
```
## Session strategy
User sessions are securely stored in the database. This allows active sessions to be managed in the security settings (i.e. you can log out all devices) and changes take effect immediately.
---
## Admin UI
**URL**: https://www.achromatic.dev/docs/starter-kits/pro-nextjs-drizzle/authentication/superadmin
**Description**: Learn how to create admin users and access the admin UI.
The starter kit comes with an admin role and a UI for managing users and organizations out of the box.
The only thing you need to do is to create a new user and assign it the admin role.
## Create admin user via database
You can create an admin user directly in the database. First, start Drizzle Studio:
```bash filename="Terminal" lineNumbers
npm run db:studio
```
Then:
1. Navigate to the `users` table
2. Create a new user or find an existing user
3. Set the `role` field to `admin`
4. Save the changes
## Assign admin role to existing user
If you have already created a user and want to make it an admin, you can update the database entry directly.
### Using Drizzle Studio
1. Start Drizzle Studio:
```bash filename="Terminal" lineNumbers
npm run db:studio
```
2. Select the `User` table and find the user you want to make an admin
3. Click on the `role` field and change it to `admin`
4. Save the changes
### Using SQL
You can also update the role directly using SQL:
```sql filename="update-user-role.sql" lineNumbers
UPDATE users SET role = 'admin' WHERE email = 'admin@example.com';
```
## Next Steps
Once you've created an admin user, you can:
- **Access the Admin Panel** - Log in and navigate to the Admin section (see [Admin Panel Overview](/docs/starter-kits/pro-nextjs-drizzle/admin-panel/overview))
- **Manage your application** - Use the admin panel to manage users, organizations, subscriptions and more
---
## Inngest
**URL**: https://www.achromatic.dev/docs/starter-kits/pro-nextjs-drizzle/background-tasks/inngest
**Description**: Integrate Inngest with your application for event-driven background workflows.
[Inngest](https://www.inngest.com) is a developer-first platform for building reliable background jobs, scheduled functions, and event-driven workflows. It provides a simple API for creating durable functions that automatically retry on failure.
Please subscribe to access this feature
;
}
// Check if user has a specific plan
const hasProPlan = billingStatus.activePlan.planId === 'pro';
const hasLifetimeAccess = billingStatus.activePlan.planId === 'lifetime';
const hasActiveSubscription =
billingStatus.subscription?.status === 'active' ||
billingStatus.subscription?.status === 'trialing';
if (!hasActiveSubscription && !hasLifetimeAccess) {
return Please subscribe to access this feature
;
}
return Premium feature content
;
}
```
### Billing Status Properties
The `getStatus` query returns:
- **`activePlan`**: The currently active plan (if any), containing `planId`, `planName`, `status`, etc.
- **`subscription`**: The active subscription object (if any), containing `status`, `currentPeriodEnd`, etc.
- **`enabled`**: Whether billing is enabled
## Server-Side Checks
### In tRPC Procedures
```typescript filename="trpc/routers/premium-feature.ts" lineNumbers
import { createTRPCRouter, protectedOrganizationProcedure } from '@/trpc/init';
import { TRPCError } from '@trpc/server';
import {
getActivePlanForOrganization,
hasActivePaidPlan,
hasSpecificPlan
} from '@/lib/billing';
export const premiumFeatureRouter = createTRPCRouter({
access: protectedOrganizationProcedure.query(async ({ ctx }) => {
const activePlan = await getActivePlanForOrganization(ctx.organization.id);
if (
!activePlan ||
(activePlan.planId === 'free' && !activePlan.isLifetime)
) {
throw new TRPCError({
code: 'FORBIDDEN',
message: 'This feature requires an active subscription'
});
}
return { data: 'premium content' };
})
});
```
### In Server Components
```typescript filename="app/(saas)/dashboard/premium/page.tsx" lineNumbers
import { getSession } from "@/lib/auth";
import { getActivePlanForOrganization } from "@/lib/billing";
import { redirect } from "next/navigation";
export default async function PremiumPage() {
const session = await getSession();
if (!session?.session.activeOrganizationId) {
redirect("/auth/sign-in");
}
const activePlan = await getActivePlanForOrganization(session.session.activeOrganizationId);
if (!activePlan || (activePlan.planId === 'free' && !activePlan.isLifetime)) {
redirect("/dashboard/choose-plan");
}
return Premium page content
;
}
```
## Organization-Based Checks
Billing is organization-based by default. All checks use the organization ID from the context:
### Client-Side
```tsx filename="components/organization-feature.tsx" lineNumbers
'use client';
import { trpc } from '@/trpc/client';
export function OrganizationFeature() {
const { data: billingStatus } =
trpc.organization.subscription.getStatus.useQuery();
if (
!billingStatus?.subscription ||
(billingStatus.subscription.status !== 'active' &&
billingStatus.subscription.status !== 'trialing')
) {
return This organization needs an active subscription
;
}
return Organization premium feature
;
}
```
### Server-Side
```typescript filename="trpc/routers/organization-feature.ts" lineNumbers
import { createTRPCRouter, protectedOrganizationProcedure } from '@/trpc/init';
import { TRPCError } from '@trpc/server';
import { hasActivePaidPlan } from '@/lib/billing';
export const organizationFeatureRouter = createTRPCRouter({
access: protectedOrganizationProcedure.query(async ({ ctx }) => {
const hasActivePlan = await hasActivePaidPlan(ctx.organization.id);
if (!hasActivePlan) {
throw new TRPCError({
code: 'FORBIDDEN',
message: 'This organization requires an active subscription'
});
}
return { data: 'organization premium content' };
})
});
```
## Plan Limits
You can also check plan limits:
```typescript filename="lib/billing/check-limits.ts" lineNumbers
import { getOrganizationPlanLimits } from '@/lib/billing/guards';
export async function checkMemberLimit(organizationId: string) {
const limits = await getOrganizationPlanLimits(organizationId);
// -1 means unlimited
if (limits.maxMembers === -1) {
return true; // Unlimited members
}
// Check current member count against limit
const currentMembers = await getMemberCount(organizationId);
return currentMembers < limits.maxMembers;
}
```
## Helper Functions
Use the built-in guard functions for common checks:
```typescript filename="lib/billing/feature-guards.ts" lineNumbers
import { TRPCError } from '@trpc/server';
import {
hasActivePaidPlan,
hasSpecificPlan,
requirePaidPlan,
requireSpecificPlan
} from '@/lib/billing';
// Require any paid plan
export async function requireActivePlan(organizationId: string) {
await requirePaidPlan(organizationId);
}
// Require a specific plan
export async function requirePlan(organizationId: string, planIds: string[]) {
await requireSpecificPlan(organizationId, planIds);
}
// Check if has active plan (doesn't throw)
export async function checkHasActivePlan(
organizationId: string
): PromiseThis feature requires an active subscription.
Upgrade nowPremium feature content
;
}
```
## Protecting Routes
You can protect entire routes based on plan status:
```typescript filename="app/(saas)/dashboard/premium/page.tsx" lineNumbers
import { getSession } from "@/lib/auth";
import { getActivePlanForOrganization } from "@/lib/billing";
import { redirect } from "next/navigation";
export default async function PremiumPage() {
const session = await getSession();
if (!session?.session.activeOrganizationId) {
redirect("/auth/sign-in");
}
const activePlan = await getActivePlanForOrganization(session.session.activeOrganizationId);
if (!activePlan || activePlan.planId === 'free') {
redirect("/dashboard/choose-plan");
}
return Premium page content
;
}
```
## Plan-Specific Access
You can also check for specific plans:
```typescript filename="lib/billing/check-access.ts" lineNumbers
import { hasSpecificPlan } from '@/lib/billing';
export async function checkPlanAccess(
organizationId: string,
requiredPlanId: string
): PromiseThis feature is only available on the Pro plan.
Upgrade to ProPro feature content
;
}
```
## Organization-Based Paywalls
Billing is organization-based by default. Use the organization context:
```typescript filename="trpc/routers/organization-feature.ts" lineNumbers
import { createTRPCRouter, protectedOrganizationProcedure } from '@/trpc/init';
import { TRPCError } from '@trpc/server';
import { requirePaidPlan } from '@/lib/billing';
export const organizationFeatureRouter = createTRPCRouter({
access: protectedOrganizationProcedure.query(async ({ ctx }) => {
// This will throw if organization doesn't have a paid plan
await requirePaidPlan(ctx.organization.id);
return { data: 'organization premium content' };
})
});
```
---
## Plans & Products
**URL**: https://www.achromatic.dev/docs/starter-kits/pro-nextjs-drizzle/billing/plans
**Description**: Learn how to manage plans and products in your application.
Plans and products are defined in `config/billing.config.ts`. This configuration determines what plans are available, their pricing, and how they appear in your pricing table.
maxStorage. Storage amounts in feature lists and plan limits are
display and configuration metadata until you add usage tracking and
server-side guards.
{posts.map((post) => (
))}
);
}
```
## Configuration
The blog collection is configured in `content-collections.ts`:
```typescript filename="content-collections.ts" lineNumbers
const posts = defineCollection({
name: 'posts',
directory: 'content/posts',
include: '**/*.{mdx,md}',
schema: z.object({
title: z.string(),
date: z.string(),
authorName: z.string(),
excerpt: z.string().optional(),
tags: z.array(z.string()),
published: z.boolean(),
content: z.string()
})
});
export default defineConfig({
collections: [posts]
});
```
## Best Practices
1. **Use descriptive filenames** - The filename becomes the URL slug
2. **Add descriptions** - Help with SEO and preview cards
3. **Use categories** - Organize related posts
4. **Set publication dates** - Control when posts appear
5. **Test locally** - Always preview posts before publishing
---
## Documentation
**URL**: https://www.achromatic.dev/docs/starter-kits/pro-nextjs-drizzle/cms/documentation
**Description**: Write and organize product documentation with Fumadocs MDX.
The starter kit includes a Fumadocs documentation site at `/docs`. Its pages are local MDX files in `content/docs`, so the documentation stays versioned with the application code.
{posts.map((post) => (
))}
);
}
```
## Best Practices
1. **Organize content** - Use clear directory structures
2. **Use schemas** - Define schemas for type safety
3. **Version control** - Commit content changes to git
4. **Test locally** - Always preview content before publishing
5. **Use MDX components** - Leverage React components in your content
---
## Common Commands
**URL**: https://www.achromatic.dev/docs/starter-kits/pro-nextjs-drizzle/codebase/commands
**Description**: A practical reference for daily development, tests and local services.
Use these commands from the repository root. They are defined in
`package.json`, so prefer them over running the underlying tools directly.
## Everyday Development
| Command | Purpose |
| ------------------- | ------------------------------------------------- |
| `npm install` | Install project dependencies |
| `npm run dev` | Start the Next.js development server on port 3000 |
| `npm run build` | Create a production build |
| `npm run start` | Serve an existing production build |
| `npm run typecheck` | Check TypeScript without emitting files |
## Environment-aware commands
Next.js loads the root `.env` file for `dev`, `build` and `start`. The test
scripts use the repository's `with-dev-env` wrapper because Vitest and
Playwright also need those values outside the Next.js process:
```sh filename="Terminal" lineNumbers
npm run with-dev-env -- {post.title}
{post.excerpt}
npm run clean removes generated output, dependencies and ignored
files from the listed build directories. Commit or back up any ignored work
you intend to keep before running it.
POSTGRES_* variables (POSTGRES_USER, POSTGRES_PASSWORD,
POSTGRES_DB, POSTGRES_HOST, POSTGRES_PORT) are optional and have defaults.
Only DATABASE_URL is required.
BETTER_AUTH_SECRET, not{' '}
AUTH_SECRET. Replace the development value copied from{' '}
.env.example before sharing or deploying the application. Every
environment should use its own secret.
main branch
to the Achromatic repository. Your commits should continue to push to your own
remote.
{appConfig.appName}
; } ``` ```typescript filename="lib/pagination.ts" lineNumbers import { appConfig } from '@/config/app.config'; export function getDefaultLimit() { return appConfig.pagination.defaultLimit; } ``` --- ## Authentication Configuration **URL**: https://www.achromatic.dev/docs/starter-kits/pro-nextjs-drizzle/configuration/auth **Description**: Configure authentication settings, redirects, and CORS. The authentication configuration file (`config/auth.config.ts`) contains settings for authentication, session management, redirects, and CORS. ## Configuration File ```typescript filename="config/auth.config.ts" lineNumbers import { env } from '@/lib/env'; import { getBaseUrl } from '@/lib/utils'; const origins = Array.from( new Set( [ getBaseUrl(), env.NEXT_PUBLIC_SITE_URL, env.NEXT_PUBLIC_VERCEL_URL ? `https://${env.NEXT_PUBLIC_VERCEL_URL}` : undefined, env.NEXT_PUBLIC_VERCEL_BRANCH_URL ? `https://${env.NEXT_PUBLIC_VERCEL_BRANCH_URL}` : undefined, env.NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL ? `https://${env.NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL}` : undefined, env.NEXT_PUBLIC_NODE_ENV === 'development' ? 'http://localhost:3000' : undefined ].filter(Boolean) as string[] ) ); export const authConfig = { redirectAfterSignIn: '/dashboard', redirectAfterLogout: '/', sessionCookieMaxAge: 60 * 60 * 24 * 30, verificationExpiresIn: 60 * 60 * 24 * 14, minimumPasswordLength: 8, trustedOrigins: origins, // Controls signup links and the starter signup page // This does not block Better Auth's signup endpoint enableSignup: true, enableSocialLogin: true, cors: { allowedOrigins: [...origins, /^https:\/\/.*\.vercel\.app$/], allowedMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'], allowedHeaders: [ 'Authorization', 'Content-Type', 'Accept', 'Origin', 'X-Requested-With', 'Access-Control-Request-Method', 'Access-Control-Request-Headers', 'X-CSRF-Token', 'Accept-Version', 'Content-Length', 'Content-MD5', 'Date', 'X-Api-Version', 'cf-connecting-ip', 'cf-ipcountry', 'cf-ray', 'cf-visitor', 'x-vercel-id', 'x-vercel-deployment-url', 'x-vercel-proxied-for', 'X-Forwarded-For', 'X-Forwarded-Host', 'X-Forwarded-Proto', 'X-Real-IP', 'Connection', 'Host', 'User-Agent', 'Referer' ], maxAge: 86_400 } } satisfies AuthConfig; ``` ## Configuration Options ### Redirects - **`redirectAfterSignIn`**: Where users are redirected after successful sign in (default: `"/dashboard"`) - **`redirectAfterLogout`**: Where users are redirected after logout (default: `"/"`) ### Session Management - **`sessionCookieMaxAge`**: Maximum age of the session cookie in seconds (default: 30 days) - **`verificationExpiresIn`**: How long email verification links are valid in seconds (default: 14 days) ### Password Requirements - **`minimumPasswordLength`**: Minimum password length required (default: `8`) ### Trusted Origins - **`trustedOrigins`**: Array of trusted origins for authentication requests - Automatically includes base URL, Vercel URLs, and localhost in development - Used for CSRF protection and secure authentication ### Signup and Login - **`enableSignup`**: Whether the starter auth cards show signup links and the signup page opens without a valid, pending invitation (default: `true`) - **`enableSocialLogin`**: Whether the starter UI shows social login buttons (default: `true`) ### CORS Configuration The `cors` object configures Cross-Origin Resource Sharing: - **`allowedOrigins`**: Array of allowed origins (includes trusted origins and Vercel preview URLs) - **`allowedMethods`**: HTTP methods allowed in CORS requests - **`allowedHeaders`**: HTTP headers allowed in CORS requests - **`maxAge`**: Maximum age for preflight requests in seconds (default: 24 hours) ## Use Cases ### Gate the Starter Signup Page To hide signup links in the starter auth cards and gate the starter signup page by invitation: ```typescript filename="config/auth.config.ts" lineNumbers export const authConfig = { // ... other config enableSignup: false }; ``` The signup page validates that the supplied invitation exists, is pending and has not expired. `enableSignup` is not a server-side policy for Better Auth's signup endpoint. A production invitation-only product must add server-side invitation validation and review every enabled signup path, including OAuth. ### Hide Social Login Buttons To hide the starter's OAuth buttons and connected accounts card: ```typescript filename="config/auth.config.ts" lineNumbers export const authConfig = { // ... other config enableSocialLogin: false }; ``` This flag does not unregister the configured OAuth provider or disable Better Auth's OAuth routes. Remove the provider from `lib/auth/index.ts` and its credentials from the environment if you want to disable the provider itself. ### Custom Redirects To customize redirect paths: ```typescript filename="config/auth.config.ts" lineNumbers export const authConfig = { // ... other config redirectAfterSignIn: '/dashboard', redirectAfterLogout: '/auth/sign-in' }; ``` ### Adjust Session Duration To change session cookie duration: ```typescript filename="config/auth.config.ts" lineNumbers export const authConfig = { // ... other config sessionCookieMaxAge: 60 * 60 * 24 * 7 // 7 days instead of 30 }; ``` ### Stricter Password Requirements To require longer passwords: ```typescript filename="config/auth.config.ts" lineNumbers export const authConfig = { // ... other config minimumPasswordLength: 12 // Require 12 characters minimum }; ``` ## Type Definitions The configuration uses TypeScript types for type safety: ```typescript filename="config/auth.config.ts" lineNumbers export type CorsConfig = { allowedOrigins: (string | RegExp)[]; allowedMethods: string[]; allowedHeaders: string[]; maxAge: number; }; export type AuthConfig = { redirectAfterSignIn: string; redirectAfterLogout: string; sessionCookieMaxAge: number; verificationExpiresIn: number; minimumPasswordLength: number; trustedOrigins: string[]; enableSignup: boolean; enableSocialLogin: boolean; cors: CorsConfig; }; ``` ## Using the Configuration Import and use the configuration in your code: ```typescript filename="lib/auth/redirects.ts" lineNumbers import { authConfig } from '@/config/auth.config'; export function getSignInRedirect() { return authConfig.redirectAfterSignIn; } ``` ```typescript filename="lib/auth/validation.ts" lineNumbers import { authConfig } from '@/config/auth.config'; export function validatePassword(password: string) { if (password.length < authConfig.minimumPasswordLength) { throw new Error( `Password must be at least ${authConfig.minimumPasswordLength} characters` ); } } ``` --- ## Billing Configuration **URL**: https://www.achromatic.dev/docs/starter-kits/pro-nextjs-drizzle/configuration/billing **Description**: Configure plans, pricing, and credit packages. The billing configuration file (`config/billing.config.ts`) contains settings for billing features, subscription plans, pricing, and credit packages for AI features. ## Configuration File The billing configuration is extensive and includes: - **Billing settings**: Enable/disable billing, default currency - **Plans**: Subscription plans with features, limits, and pricing - **Credit packages**: One-time credit purchases for AI features - **Credit costs**: Per-model pricing for AI usage ```typescript filename="config/billing.config.ts" lineNumbers import { env } from '@/lib/env'; export const billingConfig = { // Enable/disable billing feature enabled: true, // Default currency defaultCurrency: 'usd', // Plans configuration plans: { // Free tier - no Stripe price needed free: { id: 'free', name: 'Free', description: 'Get started with basic features', isFree: true, features: [ 'Up to 3 team members', 'Basic analytics', 'Community support', '1 GB storage' ], limits: { maxMembers: 3, maxStorage: 1 // GB } }, // Pro plan - main paid tier pro: { id: 'pro', name: 'Pro', description: 'For growing teams', recommended: true, features: [ 'Unlimited team members', 'Advanced analytics', 'Priority support', '100 GB storage', 'Custom integrations', 'API access' ], limits: { maxMembers: -1, // unlimited maxStorage: 100 // GB }, prices: [ { id: 'pro_monthly', stripePriceId: env.NEXT_PUBLIC_STRIPE_PRICE_PRO_MONTHLY ?? '', type: 'recurring', interval: 'month', intervalCount: 1, amount: 2900, // $29.00 in cents currency: 'usd', seatBased: true, // Per-seat pricing trialDays: 14 }, { id: 'pro_yearly', stripePriceId: env.NEXT_PUBLIC_STRIPE_PRICE_PRO_YEARLY ?? '', type: 'recurring', interval: 'year', intervalCount: 1, amount: 27800, // $278.00 in cents currency: 'usd', seatBased: true, trialDays: 14 } ] }, // Lifetime deal - one-time order lifetime: { id: 'lifetime', name: 'Lifetime', description: 'Pay once, use forever', features: [ 'All Pro features', 'Lifetime updates', 'Priority support for 1 year', '100 GB storage' ], limits: { maxMembers: -1, maxStorage: 100 }, prices: [ { id: 'lifetime_once', stripePriceId: env.NEXT_PUBLIC_STRIPE_PRICE_LIFETIME ?? '', type: 'one_time', amount: 49900, // $499.00 in cents currency: 'usd' } ] } } } satisfies BillingConfig; ```maxStorage or meter stored
bytes. Treat storage amounts as plan metadata until you add usage tracking and
server-side enforcement.
This uses Geist Sans
This uses Literata
```
---
## Naming & Branding
**URL**: https://www.achromatic.dev/docs/starter-kits/pro-nextjs-drizzle/customization/naming
**Description**: Learn how to change the app name, description, and metadata throughout your application.
## App Name and Description
The app name and description are used throughout the application. Update them in the configuration file:
```typescript filename="config/app.config.ts" lineNumbers
export const appConfig = {
appName: 'Your App Name',
description: 'A fantastic SaaS to make your life easier.',
baseUrl: 'https://yourdomain.com'
// ...
};
```
This configuration is used in:
- Navigation and headers
- Email templates
- SEO metadata
- Social sharing
## Metadata
The metadata in `app/layout.tsx` automatically uses values from `appConfig`:
```typescript filename="app/layout.tsx" lineNumbers
import { appConfig } from '@/config/app.config';
export const metadata: Metadata = {
metadataBase: new URL(appConfig.baseUrl),
title: {
absolute: appConfig.appName,
default: appConfig.appName,
template: `%s | ${appConfig.appName}`
},
description: appConfig.description,
openGraph: {
type: 'website',
locale: 'en_US',
siteName: appConfig.appName,
title: appConfig.appName,
description: appConfig.description
},
twitter: {
card: 'summary_large_image',
title: appConfig.appName,
description: appConfig.description
}
};
```
## Package.json
Update the name and description in `package.json`:
```json filename="package.json" lineNumbers
{
"name": "your-app-name",
"version": "1.0.0",
"description": "Your app description",
"author": "Your Name",
"license": "MIT"
// ...
}
```
## Environment Variables
The `baseUrl` in `appConfig` uses `getBaseUrl()` which reads from `NEXT_PUBLIC_SITE_URL` if set, otherwise falls back to the request URL. You can set it in your `.env`:
```env filename=".env" lineNumbers
NEXT_PUBLIC_SITE_URL=https://yourdomain.com
```
## Email Branding
Update email templates to reflect your branding. Email templates are located in `lib/email/templates/`:
```typescript filename="lib/email/templates/welcome-email.tsx" lineNumbers
export function WelcomeEmail({ name }: { name: string }) {
return (
lib/db/migrations/ and should be
committed to version control. Each migration has a unique name and contains
the SQL statements needed to apply the changes.
db:push is useful for development but should not be used in
production. Always use migrations (db:generate and{' '}
db:migrate) for production deployments.
lib/db/migrations/ and are version
controlled. Each migration has a unique name and contains the SQL statements
needed to apply the changes.
db:push is useful for development but should not be used in
production. Always use migrations (db:generate and{' '}
db:migrate) for production deployments.
https://local.drizzle.studio
Welcome to our platform!
', text: 'Welcome to our platform!' }); ``` ## Email Templates The starter kit uses [React Email](https://react.email/) to create email templates using `.tsx` files..env is in your .gitignore.
onboarding@resend.dev. However, for production, always use your
own verified domain for better deliverability.
Welcome to our platform!
', text: 'Welcome to our platform!' }); ``` ### Using Pre-built Templates The email module exports functions for all pre-built templates: ```typescript filename="lib/actions/signup.ts" lineNumbers import { sendVerifyEmailAddressEmail } from '@/lib/email'; await sendVerifyEmailAddressEmail({ recipient: user.email, name: user.name, verificationLink: `${getBaseUrl()}/verify-email?token=${token}` }); ``` ## Retry Logic The email service includes automatic retry logic with exponential backoff: - **Max Attempts**: 3 total attempts (the initial attempt and up to 2 retries) - **Base Delay**: 1 second - **Max Delay**: 10 seconds - **Exponential Backoff**: Delay doubles with each retry Permanent errors (invalid email, auth failure) are not retried. ## Error Handling The email functions handle errors gracefully: ```typescript filename="lib/email/example.ts" lineNumbers import { sendEmail } from '@/lib/email'; try { await sendEmail({ recipient: 'user@example.com', subject: 'Test', html: 'Test
', text: 'Test' }); } catch (error) { // Error is logged automatically // Permanent errors are not retried // Transient errors are retried automatically } ``` ## Production Configuration For production deployments: 1. **Use a verified domain** - Always use your own domain, not Resend's default 2. **Set up SPF/DKIM** - Ensure DNS records are properly configured 3. **Monitor deliverability** - Check Resend dashboard for bounce rates 4. **Set up webhooks** (optional) - Track email events (delivered, bounced, etc.) ### Environment Variables in Production Add your environment variables in your hosting platform: - **Vercel**: Project Settings → Environment Variables - **Railway**: Variables tab - **Other platforms**: Follow their environment variable documentation ## Testing Test templates and delivery separately. A correct preview does not prove that Resend can authenticate your sender or deliver a message. ### Preview templates locally Run `npm run email:dev`, then open `http://localhost:3001`. This renders the components in `lib/email/templates/` with their `PreviewProps` without sending email or calling Resend. See [React Email Preview](/docs/starter-kits/pro-nextjs-drizzle/email/react-email-preview). ### Verify provider delivery 1. Set `RESEND_API_KEY` to a development API key. 2. Set `EMAIL_FROM` to an address on a verified domain. For an initial Resend test, `onboarding@resend.dev` can only send to the email address associated with your Resend account. 3. Start the application and trigger a real product flow such as email verification, password reset or an organization invitation. 4. Confirm the request succeeds, the message appears in the Resend dashboard and the recipient receives it. 5. Open the generated link and confirm that it uses the correct application URL for the environment you are testing.Welcome to our platform!
', text: 'Welcome to our platform!' }); ``` For a reusable product email, create a typed React Email template and an exported rendering function in `lib/email/emails.ts`. This guarantees that HTML and plain-text versions are generated consistently.http://localhost:3001 and
automatically detects all email templates in lib/email/templates/
.
{posts.map((post) => (
))}
);
}
```
## Configuration
The blog collection is configured in `content-collections.ts`:
```typescript filename="content-collections.ts" lineNumbers
const posts = defineCollection({
name: 'posts',
directory: 'content/posts',
include: '**/*.{mdx,md}',
schema: z.object({
title: z.string(),
date: z.string(),
authorName: z.string(),
excerpt: z.string().optional(),
tags: z.array(z.string()),
published: z.boolean(),
content: z.string()
})
});
export default defineConfig({
collections: [posts]
});
```
## Best Practices
1. **Use descriptive filenames** - The filename becomes the URL slug
2. **Add descriptions** - Help with SEO and preview cards
3. **Use categories** - Organize related posts
4. **Set publication dates** - Control when posts appear
5. **Test locally** - Always preview posts before publishing
---
## Contact Page
**URL**: https://www.achromatic.dev/docs/starter-kits/pro-nextjs-drizzle/marketing/contact
**Description**: Learn how to customize the contact page and configure contact information.
The contact page (`/contact`) provides a way for visitors to get in touch with your team. It includes a contact form and displays your contact information.
## Page Structure
The contact page is located at `app/contact/page.tsx` and includes:
- **Contact Hero Section** - Headline and description
- **Contact Form** - Form for visitors to send messages
- **FAQ Section** - Frequently asked questions
## Configuration
Contact information is configured in `config/app.config.ts`:
```typescript filename="config/app.config.ts" lineNumbers
export const appConfig = {
// ... other config
contact: {
enabled: true,
email: 'hello@yourdomain.com',
phone: '(123) 456-7890',
address: '123 Main St, San Francisco, CA'
}
};
```
### Contact Form
The contact form is handled by the `ContactHeroSection` component. To customize the form:
1. **Update form fields** - Edit the form component in `components/sections/contact-hero-section.tsx`
2. **Configure email** - Set up email sending in your email service (see [Email documentation](/docs/starter-kits/pro-nextjs-drizzle/email/overview))
3. **Add validation** - Add client and server-side validation as needed
## Customization
### Update Contact Content
Edit the `ContactHeroSection` component:
```typescript filename="components/sections/contact-hero-section.tsx" lineNumbers
export function ContactHeroSection(): React.JSX.Element {
return (
{post.title}
{post.excerpt}
Get in Touch
We'd love to hear from you
{/* Contact form */}Your Headline
Your value proposition
{posts.map((post) => (
))}
);
}
```
## Best Practices
1. **Organize content** - Use clear directory structures
2. **Use schemas** - Define schemas for type safety
3. **Version control** - Commit content changes to git
4. **Test locally** - Always preview content before publishing
5. **Use MDX components** - Leverage React components in your content
---
## Pricing Page
**URL**: https://www.achromatic.dev/docs/starter-kits/pro-nextjs-drizzle/marketing/pricing
**Description**: Learn how to customize the pricing page and integrate it with your billing configuration.
The pricing page (`/pricing`) displays your subscription plans and pricing information. It's integrated with your billing configuration and automatically displays plans from `config/billing.config.ts`.
## Page Structure
The pricing page is located at `app/pricing/page.tsx` and includes:
- **Pricing Hero Section** - Headline and description for the pricing page
- **Pricing Section** - Displays all plans from your billing configuration
- **FAQ Section** - Frequently asked questions about pricing
## Integration with Billing Config
The pricing page automatically reads plans from `config/billing.config.ts`. Plans are displayed based on:
- **Plan visibility** - Plans with `hidden: true` are not shown
- **Plan order** - Plans are displayed in the order they appear in the config
- **Recommended plans** - Plans with `recommended: true` are highlighted
- **Enterprise plans** - Plans with `isEnterprise: true` show a "Contact Sales" button
## Customization
### Update Pricing Content
Edit the `PricingHeroSection` component:
```typescript filename="components/sections/pricing-hero-section.tsx" lineNumbers
export function PricingHeroSection(): React.JSX.Element {
return (
{post.title}
{post.excerpt}
Choose Your Plan
Select the perfect plan for your needs
project:read and project:releases scopes.
attachRpcInput: true and adds
the authenticated user's ID and email to the Sentry scope. Server
instrumentation also sets sendDefaultPii: true. Remove
unnecessary input fields, disable default PII or scrub events in{' '}
beforeSend before processing real customer data. Never send
passwords, tokens, payment details or other secrets to Sentry.
Loading...
;
if (!posts?.length) return No posts found
;
return (
{posts.map((post) => (
))}
);
}
```
## Updating Organization Data
### Update with Permission Check
Only allow admins to update organization-scoped data:
```typescript filename="trpc/routers/posts.ts" lineNumbers
update: protectedOrganizationProcedure
.input(
z.object({
id: z.string(),
title: z.string().optional(),
content: z.string().optional(),
})
)
.mutation(async ({ input, ctx }) => {
// Check if user is admin or owner
const isAdmin =
ctx.membership.role === "admin" || ctx.membership.role === "owner";
const post = await db.query.postsTable.findFirst({
where: and(
eq(postsTable.id, input.id),
eq(postsTable.organizationId, ctx.organization.id)
),
});
if (!post) {
throw new TRPCError({ code: "NOT_FOUND" });
}
// Only author or admin can update
if (post.authorId !== ctx.user.id && !isAdmin) {
throw new TRPCError({
code: "FORBIDDEN",
message: "You can only edit your own posts or be an admin",
});
}
const [updatedPost] = await db
.update(postsTable)
.set({
title: input.title,
content: input.content,
updatedAt: new Date(),
})
.where(eq(postsTable.id, input.id))
.returning();
return updatedPost;
}),
```
## Best Practices
1. **Always scope by organizationId** - Never query without organization scope
2. **Use protectedOrganizationProcedure** - Automatically handles scoping
3. **Verify membership** - Always verify user is a member before operations
4. **Check permissions** - Verify roles before allowing modifications
5. **Cascade deletes** - Use `onDelete: "cascade"` for organization-scoped data
6. **Index organizationId** - Add database indexes on `organizationId` for performance
---
## Use Organizations
**URL**: https://www.achromatic.dev/docs/starter-kits/pro-nextjs-drizzle/organizations/use-organizations
**Description**: Learn how to use organizations in your application.
In the starter kit, the active organization is stored in the Better Auth session. The active organization ID is available in `session.activeOrganizationId` and can be accessed using Better Auth's hooks and APIs.
## How Active Organization Works
The active organization is managed by Better Auth and stored in the user's session. When a user switches organizations, the `activeOrganizationId` in the session is updated, and this organization becomes available throughout your application.
## Client-Side Usage
### Using Better Auth's Hook
Use `authClient.useActiveOrganization()` to access the active organization:
```tsx filename="components/organization-content.tsx" lineNumbers
'use client';
import { authClient } from '@/lib/auth/client';
export function OrganizationContent() {
const { data: activeOrganization, isPending } =
authClient.useActiveOrganization();
if (isPending) {
return {post.title}
{post.content}
Loading...
;
}
if (!activeOrganization) {
return No active organization found
;
}
return (
{activeOrganization.name}
Active Org ID: {activeOrganizationId}
;
}
```
## Server-Side Usage
### Get Active Organization from Session
Get the active organization from the session:
```tsx filename="app/(saas)/dashboard/organization/page.tsx" lineNumbers
import { getOrganizationById, getSession } from '@/lib/auth/server';
export default async function OrganizationPage() {
const session = await getSession();
if (!session?.session.activeOrganizationId) {
return No active organization
;
}
const organization = await getOrganizationById(
session.session.activeOrganizationId
);
if (!organization) {
return Organization not found
;
}
return Active organization: {organization.name}
;
}
```
### Get Organization by ID
Get organization data for a specific organization ID:
```typescript filename="lib/organization/get-organization.ts" lineNumbers
import { getOrganizationById } from '@/lib/auth/server';
export async function getOrganization(organizationId: string) {
const organization = await getOrganizationById(organizationId);
return organization;
}
```
### Using in tRPC
The active organization is automatically available in `protectedOrganizationProcedure`:
```typescript filename="trpc/routers/organization/index.ts" lineNumbers
import { createTRPCRouter, protectedOrganizationProcedure } from '@/trpc/init';
import { TRPCError } from '@trpc/server';
import { z } from 'zod';
export const organizationRouter = createTRPCRouter({
get: protectedOrganizationProcedure.query(async ({ ctx }) => {
// ctx.organization is guaranteed to exist
// ctx.membership contains the user's role
return {
organization: ctx.organization,
role: ctx.membership.role
};
}),
update: protectedOrganizationProcedure
.input(z.object({ name: z.string() }))
.mutation(async ({ input, ctx }) => {
// Only allow admins/owners to update
if (ctx.membership.role !== 'admin' && ctx.membership.role !== 'owner') {
throw new TRPCError({
code: 'FORBIDDEN',
message: 'Only admins can update organizations'
});
}
// Update organization using Better Auth API
await authClient.organization.update({
organizationId: ctx.organization.id,
name: input.name
});
return { success: true };
})
});
```
## Organization Switching
### Client-Side Switching
Switch organizations using Better Auth's API:
```tsx filename="components/organization-switcher.tsx" lineNumbers
'use client';
import { useRouter } from 'next/navigation';
import { authClient } from '@/lib/auth/client';
export function OrganizationSwitcher() {
const router = useRouter();
const handleSwitch = async (organizationId: string) => {
try {
// Set the active organization in Better Auth session
await authClient.organization.setActive({
organizationId
});
// Navigate to the organization dashboard
router.push('/dashboard/organization');
} catch (error) {
console.error('Failed to switch organization:', error);
}
};
return (
);
}
```
### Server-Side Switching
Update the active organization in the session:
```typescript filename="app/api/organization/switch/route.ts" lineNumbers
import { headers } from 'next/headers';
import { NextResponse } from 'next/server';
import { auth } from '@/lib/auth';
import { assertUserIsOrgMember, getSession } from '@/lib/auth/server';
export async function POST(request: Request) {
const { organizationId } = await request.json();
const session = await getSession();
if (!session) {
return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
}
// Verify user is member of organization
await assertUserIsOrgMember(organizationId, session.user.id);
// Update active organization in session
await auth.api.setActiveOrganization({
headers: await headers(),
body: {
organizationId
}
});
return NextResponse.json({ success: true });
}
```
## Listing User's Organizations
Get all organizations a user is a member of:
```typescript filename="trpc/routers/organization/index.ts" lineNumbers
import { createTRPCRouter, protectedProcedure } from '@/trpc/init';
import { asc, eq, getTableColumns } from 'drizzle-orm';
import { db } from '@/lib/db';
import { memberTable, organizationTable } from '@/lib/db/schema';
export const organizationRouter = createTRPCRouter({
list: protectedProcedure.query(async ({ ctx }) => {
const organizations = await db
.select({
...getTableColumns(organizationTable),
membersCount: db
.$count(
memberTable,
eq(memberTable.organizationId, organizationTable.id)
)
.as('membersCount')
})
.from(organizationTable)
.innerJoin(
memberTable,
eq(organizationTable.id, memberTable.organizationId)
)
.where(eq(memberTable.userId, ctx.user.id))
.orderBy(asc(organizationTable.createdAt));
return organizations.map((org) => ({
...org,
slug: org.slug || ''
}));
})
});
```
Client-side:
```tsx filename="components/organizations-list.tsx" lineNumbers
'use client';
import { trpc } from '@/trpc/client';
export function OrganizationsList() {
const { data: organizations, isLoading } = trpc.organization.list.useQuery();
if (isLoading) return Loading...
;
return (
{organizations?.map((org) => (
);
}
```
## Best Practices
1. **Always check membership** - Verify user is a member before allowing access
2. **Use protectedOrganizationProcedure** - Automatically handles organization scoping
3. **Handle loading states** - Show loading indicators while fetching organization
4. **Handle missing organizations** - Provide fallback UI when no organization is active
5. **Validate permissions** - Check roles before allowing actions
6. **Use session-based approach** - The active organization is stored in the session, not the URL
---
## Favicons & Icons
**URL**: https://www.achromatic.dev/docs/starter-kits/pro-nextjs-drizzle/recipes/favicons
**Description**: Learn how to generate and integrate favicons and app icons for your project.
## Generating a favicon
1. Visit [Favicon Generator](https://www.favicon-generator.org/).
2. Upload an image (recommended size: **at least 512×512px** for optimal resizing).
3. Click on **Create Favicon**
## Downloading
Click **Download** to save the generated files.
## Copying and overwriting
1. Select all downloaded files, **excluding** `browserconfig.xml` and `manifest.json`.
2. Copy and paste the files into the `public` directory.
## Updating metadata
Update the favicon references in `app/layout.tsx`:
```tsx filename="app/layout.tsx" lineNumbers
export const metadata = {
icons: {
icon: '/favicon.ico',
apple: '/apple-touch-icon.png'
}
// ...
};
```
{org.name}
))}
This uses Geist Sans
This uses Literata
```
---
## Naming & Branding
**URL**: https://www.achromatic.dev/docs/starter-kits/pro-nextjs-drizzle/recipes/naming
**Description**: Learn how to change the app name, description, and metadata throughout your application.
## App Name and Description
The app name and description are used throughout the application. Update them in the configuration file:
```typescript filename="config/app.config.ts" lineNumbers
export const appConfig = {
appName: 'Your App Name',
description: 'A fantastic SaaS to make your life easier.',
baseUrl: 'https://yourdomain.com'
// ...
};
```
This configuration is used in:
- Navigation and headers
- Email templates
- SEO metadata
- Social sharing
## Metadata
The metadata in `app/layout.tsx` automatically uses values from `appConfig`:
```typescript filename="app/layout.tsx" lineNumbers
import { appConfig } from '@/config/app.config';
export const metadata: Metadata = {
metadataBase: new URL(appConfig.baseUrl),
title: {
absolute: appConfig.appName,
default: appConfig.appName,
template: `%s | ${appConfig.appName}`
},
description: appConfig.description,
openGraph: {
type: 'website',
locale: 'en_US',
siteName: appConfig.appName,
title: appConfig.appName,
description: appConfig.description
},
twitter: {
card: 'summary_large_image',
title: appConfig.appName,
description: appConfig.description
}
};
```
## Package.json
Update the name and description in `package.json`:
```json filename="package.json" lineNumbers
{
"name": "your-app-name",
"version": "1.0.0",
"description": "Your app description",
"author": "Your Name",
"license": "MIT"
// ...
}
```
## Environment Variables
The `baseUrl` in `appConfig` uses `getBaseUrl()` which reads from `NEXT_PUBLIC_SITE_URL` if set, otherwise falls back to the request URL. You can set it in your `.env`:
```env filename=".env" lineNumbers
NEXT_PUBLIC_SITE_URL=https://yourdomain.com
```
## Email Branding
Update email templates to reflect your branding. Email templates are located in `lib/email/templates/`:
```typescript filename="lib/email/templates/welcome-email.tsx" lineNumbers
export function WelcomeEmail({ name }: { name: string }) {
return (
/storage/[...path] route does not read a session or check
ownership. Anyone who knows an image key can ask the application for a signed
download redirect. Add a protected route and file ownership metadata before
storing private files.
/storage/[...path] route will generate a one-hour
signed download URL for anyone who knows a valid image key. A signed URL
limits how long storage credentials can be used, but it does not prove file
ownership or organization membership.
550e8400.png. If you need
nested keys such as users/123/avatar.png, update the route to
join all remaining path segments before requesting the object.
Loading...
;
if (!user) return Not found
;
return Hello, {user.name}!
;
}
```
### Mutations
For actions that modify data, use mutations.
```tsx filename="components/update-profile-form.tsx" lineNumbers
'use client';
import { trpc } from '@/trpc/client';
import { useForm } from 'react-hook-form';
export function UpdateProfileForm() {
const utils = trpc.useUtils();
const updateProfile = trpc.user.updateProfile.useMutation({
onSuccess: () => {
// Invalidate and refetch
utils.user.getProfile.invalidate();
}
});
const onSubmit = async (data: { name: string }) => {
await updateProfile.mutateAsync(data);
};
return ;
}
```
### Optimistic Updates
For better UX, use optimistic updates:
```tsx filename="components/optimistic-update.tsx" lineNumbers
'use client';
import { trpc } from '@/trpc/client';
export function OptimisticComponent() {
const utils = trpc.useUtils();
const updateMutation = trpc.user.updateProfile.useMutation({
onMutate: async (newData) => {
// Cancel outgoing refetches
await utils.user.getProfile.cancel();
// Snapshot previous value
const previous = utils.user.getProfile.getData();
// Optimistically update
utils.user.getProfile.setData(undefined, (old) => ({
...old!,
...newData
}));
return { previous };
},
onError: (err, newData, context) => {
// Rollback on error
utils.user.getProfile.setData(undefined, context?.previous);
},
onSettled: () => {
// Refetch to ensure consistency
utils.user.getProfile.invalidate();
}
});
// ... use mutation
}
```
## Server-Side Usage
### Prefetching
For better performance, prefetch data on the server in your Next.js Server Components.
```tsx filename="app/(saas)/dashboard/profile/page.tsx" lineNumbers
import { HydrateClient, trpc } from '@/trpc/server';
export default async function ProfilePage() {
// Prefetch data on the server
await trpc.user.getProfile.prefetch();
return (
Data not found
;
}
return Error: {error.message}
;
}
if (isLoading) return Loading...
;
return {data}
;
}
```
## Best Practices
1. **Use appropriate procedures** - Choose `publicProcedure`, `protectedProcedure` or `protectedOrganizationProcedure` based on your needs
2. **Validate inputs** - Always use Zod schemas for input validation
3. **Handle errors** - Use `TRPCError` for consistent error handling
4. **Optimize queries** - Use prefetching and optimistic updates for better UX
5. **Type safety** - Leverage TypeScript inference for type safety
---
## Define Endpoint
**URL**: https://www.achromatic.dev/docs/starter-kits/pro-nextjs-drizzle/trpc/define-endpoint
**Description**: Learn how to create new tRPC endpoints.
This guide shows you how to create new tRPC endpoints in your application. We'll create a complete CRUD example for a `posts` feature.
## Creating a Router
Create a new router file in `trpc/routers/`:
```typescript filename="trpc/routers/posts.ts" lineNumbers
import { protectedProcedure, router } from '@/trpc/init';
import { eq } from 'drizzle-orm';
import { z } from 'zod';
import { db } from '@/lib/db';
import { postsTable } from '@/lib/db/schema';
export const postsRouter = router({
// Endpoints will go here
});
```
## List Posts (Query)
Create a query to list posts:
```typescript filename="trpc/routers/posts.ts" lineNumbers
list: protectedProcedure
.input(
z.object({
limit: z.number().min(1).max(100).default(10),
offset: z.number().min(0).default(0),
})
)
.query(async ({ input, ctx }) => {
const posts = await db.query.postsTable.findMany({
limit: input.limit,
offset: input.offset,
orderBy: (posts, { desc }) => [desc(posts.createdAt)],
});
return posts;
}),
```
## Create Post (Mutation)
Create a mutation to create a new post:
```typescript filename="trpc/routers/posts.ts" lineNumbers
create: protectedProcedure
.input(
z.object({
title: z.string().min(1).max(255),
content: z.string().min(1),
})
)
.mutation(async ({ input, ctx }) => {
const [post] = await db
.insert(postsTable)
.values({
title: input.title,
content: input.content,
authorId: ctx.session.user.id,
})
.returning();
return post;
}),
```
## Get Post by ID (Query)
Create a query to get a single post:
```typescript filename="trpc/routers/posts.ts" lineNumbers
getById: protectedProcedure
.input(z.object({ id: z.string() }))
.query(async ({ input }) => {
const post = await db.query.postsTable.findFirst({
where: eq(postsTable.id, input.id),
});
if (!post) {
throw new TRPCError({
code: "NOT_FOUND",
message: "Post not found",
});
}
return post;
}),
```
## Update Post (Mutation)
Create a mutation to update a post:
```typescript filename="trpc/routers/posts.ts" lineNumbers
update: protectedProcedure
.input(
z.object({
id: z.string(),
title: z.string().min(1).max(255).optional(),
content: z.string().min(1).optional(),
})
)
.mutation(async ({ input, ctx }) => {
// Verify post exists and user is author
const existingPost = await db.query.postsTable.findFirst({
where: eq(postsTable.id, input.id),
});
if (!existingPost) {
throw new TRPCError({
code: "NOT_FOUND",
message: "Post not found",
});
}
if (existingPost.authorId !== ctx.session.user.id) {
throw new TRPCError({
code: "FORBIDDEN",
message: "You are not the author of this post",
});
}
const [updatedPost] = await db
.update(postsTable)
.set({
title: input.title,
content: input.content,
updatedAt: new Date(),
})
.where(eq(postsTable.id, input.id))
.returning();
return updatedPost;
}),
```
## Delete Post (Mutation)
Create a mutation to delete a post:
```typescript filename="trpc/routers/posts.ts" lineNumbers
delete: protectedProcedure
.input(z.object({ id: z.string() }))
.mutation(async ({ input, ctx }) => {
// Verify post exists and user is author
const existingPost = await db.query.postsTable.findFirst({
where: eq(postsTable.id, input.id),
});
if (!existingPost) {
throw new TRPCError({
code: "NOT_FOUND",
message: "Post not found",
});
}
if (existingPost.authorId !== ctx.session.user.id) {
throw new TRPCError({
code: "FORBIDDEN",
message: "You are not the author of this post",
});
}
await db.delete(postsTable).where(eq(postsTable.id, input.id));
return { success: true };
}),
```
## Complete Router Example
Here's the complete router:
```typescript filename="trpc/routers/posts.ts" lineNumbers
import { protectedProcedure, router } from '@/trpc/init';
import { TRPCError } from '@trpc/server';
import { desc, eq } from 'drizzle-orm';
import { z } from 'zod';
import { db } from '@/lib/db';
import { postsTable } from '@/lib/db/schema';
export const postsRouter = router({
list: protectedProcedure
.input(
z.object({
limit: z.number().min(1).max(100).default(10),
offset: z.number().min(0).default(0)
})
)
.query(async ({ input }) => {
return await db.query.postsTable.findMany({
limit: input.limit,
offset: input.offset,
orderBy: [desc(postsTable.createdAt)]
});
}),
getById: protectedProcedure
.input(z.object({ id: z.string() }))
.query(async ({ input }) => {
const post = await db.query.postsTable.findFirst({
where: eq(postsTable.id, input.id)
});
if (!post) {
throw new TRPCError({
code: 'NOT_FOUND',
message: 'Post not found'
});
}
return post;
}),
create: protectedProcedure
.input(
z.object({
title: z.string().min(1).max(255),
content: z.string().min(1)
})
)
.mutation(async ({ input, ctx }) => {
const [post] = await db
.insert(postsTable)
.values({
title: input.title,
content: input.content,
authorId: ctx.session.user.id
})
.returning();
return post;
}),
update: protectedProcedure
.input(
z.object({
id: z.string(),
title: z.string().min(1).max(255).optional(),
content: z.string().min(1).optional()
})
)
.mutation(async ({ input, ctx }) => {
const existingPost = await db.query.postsTable.findFirst({
where: eq(postsTable.id, input.id)
});
if (!existingPost) {
throw new TRPCError({ code: 'NOT_FOUND' });
}
if (existingPost.authorId !== ctx.session.user.id) {
throw new TRPCError({ code: 'FORBIDDEN' });
}
const [updatedPost] = await db
.update(postsTable)
.set({
title: input.title,
content: input.content,
updatedAt: new Date()
})
.where(eq(postsTable.id, input.id))
.returning();
return updatedPost;
}),
delete: protectedProcedure
.input(z.object({ id: z.string() }))
.mutation(async ({ input, ctx }) => {
const existingPost = await db.query.postsTable.findFirst({
where: eq(postsTable.id, input.id)
});
if (!existingPost) {
throw new TRPCError({ code: 'NOT_FOUND' });
}
if (existingPost.authorId !== ctx.session.user.id) {
throw new TRPCError({ code: 'FORBIDDEN' });
}
await db.delete(postsTable).where(eq(postsTable.id, input.id));
return { success: true };
})
});
```
## Adding Router to App Router
Add your new router to the main app router:
```typescript filename="trpc/routers/app.ts" lineNumbers
import { createTRPCRouter } from '@/trpc/init';
import { lazy } from '@trpc/server';
export const appRouter = createTRPCRouter({
admin: lazy(() => import('./admin')),
organization: lazy(() => import('./organization')),
user: lazy(() => import('./user')),
posts: lazy(() => import('./posts')) // Add your new router
// ... other routers
});
export type AppRouter = typeof appRouter;
```
## Using the Endpoint
### Client-Side
```tsx filename="components/posts-list.tsx" lineNumbers
'use client';
import { trpc } from '@/trpc/client';
export function PostsList() {
const { data: posts, isLoading } = trpc.posts.list.useQuery({
limit: 10,
offset: 0
});
if (isLoading) return Loading...
;
return (
{posts?.map((post) => (
))}
);
}
```
### Server-Side
```tsx filename="app/(saas)/dashboard/posts/page.tsx" lineNumbers
import { HydrateClient, trpc } from '@/trpc/server';
export default async function PostsPage() {
await trpc.posts.list.prefetch({ limit: 10, offset: 0 });
return (
{post.title}
{post.content}
Loading...
;
if (error) return Error: {error.message}
;
if (!user) return Not found
;
return Hello, {user.name}!
;
}
```
### Query with Input
Pass input parameters to queries:
```tsx filename="components/post-detail.tsx" lineNumbers
'use client';
import { trpc } from '@/trpc/client';
export function PostDetail({ postId }: { postId: string }) {
const { data: post, isLoading } = trpc.posts.getById.useQuery({ id: postId });
if (isLoading) return Loading...
;
if (!post) return Post not found
;
return (
{post.title}
{post.content}
{/* render data */}
;
}
```
## Mutations
Use `useMutation` for data modifications:
```tsx filename="components/create-post-form.tsx" lineNumbers
'use client';
import { trpc } from '@/trpc/client';
import { useForm } from 'react-hook-form';
export function CreatePostForm() {
const utils = trpc.useUtils();
const { handleSubmit } = useForm<{ title: string; content: string }>();
const createPost = trpc.posts.create.useMutation({
onSuccess: () => {
// Invalidate and refetch posts list
utils.posts.list.invalidate();
}
});
const onSubmit = async (data: { title: string; content: string }) => {
try {
await createPost.mutateAsync(data);
// Handle success
} catch (error) {
// Handle error
}
};
return ;
}
```
### Optimistic Updates
Update the UI optimistically for better UX:
```tsx filename="components/optimistic-update.tsx" lineNumbers
'use client';
import { trpc } from '@/trpc/client';
export function OptimisticUpdate() {
const utils = trpc.useUtils();
const updatePost = trpc.posts.update.useMutation({
onMutate: async (newData) => {
// Cancel outgoing refetches
await utils.posts.getById.cancel({ id: newData.id });
// Snapshot previous value
const previous = utils.posts.getById.getData({ id: newData.id });
// Optimistically update
utils.posts.getById.setData({ id: newData.id }, (old) => ({
...old!,
...newData
}));
return { previous };
},
onError: (err, newData, context) => {
// Rollback on error
utils.posts.getById.setData({ id: newData.id }, context?.previous);
},
onSettled: (data, error, variables) => {
// Refetch to ensure consistency
utils.posts.getById.invalidate({ id: variables.id });
}
});
return (
);
}
```
## Server-Side Usage
### Prefetching in Server Components
Prefetch data on the server for better performance:
```tsx filename="app/(saas)/dashboard/posts/page.tsx" lineNumbers
import { HydrateClient, trpc } from '@/trpc/server';
export default async function PostsPage() {
// Prefetch data on the server
await trpc.posts.list.prefetch({ limit: 10, offset: 0 });
return (
Post not found
;
}
if (error.data?.code === 'FORBIDDEN') {
return You don't have permission to view this post
;
}
return Error: {error.message}
;
}
if (isLoading) return Loading...
;
return {/* render data */}
;
}
```
## Type Inference
Extract types from your procedures:
```typescript filename="types/post.ts" lineNumbers
import type { AppRouter } from '@/trpc/routers/app';
import type { inferRouterInputs, inferRouterOutputs } from '@trpc/server';
type RouterOutputs = inferRouterOutputs{post?.title}
;
}
```
## Query Invalidation
Invalidate queries to trigger refetches:
```tsx filename="components/invalidation.tsx" lineNumbers
'use client';
import { trpc } from '@/trpc/client';
export function InvalidationExample() {
const utils = trpc.useUtils();
const createPost = trpc.posts.create.useMutation();
const handleCreate = async (data: { title: string; content: string }) => {
await createPost.mutateAsync(data);
// Invalidate specific query
utils.posts.list.invalidate();
// Or invalidate all posts queries
utils.posts.invalidate();
};
return (
);
}
```
## Best Practices
1. **Use prefetching** - Prefetch data on the server for better performance
2. **Handle loading states** - Always show loading indicators
3. **Handle errors** - Provide user-friendly error messages
4. **Use optimistic updates** - Update UI immediately for better UX
5. **Invalidate queries** - Invalidate related queries after mutations
6. **Type safety** - Leverage TypeScript inference for type safety