Mahdi BEN RHOUMA

Posted on Jun 14 • Originally published at iloveblogs.blog

Complete Type Safety Guide for Next.js and Supabase with TypeScript

#typescript #nextjs #supabase #typesafety

Complete Type Safety Guide for Next.js and Supabase with TypeScript

TypeScript catches errors at compile time. But without proper setup, your Supabase queries are just strings with any types. You lose autocomplete, type checking, and the safety TypeScript promises.

This guide shows you how to achieve end-to-end type safety: from database schema to UI components, with runtime validation and compile-time guarantees.

Prerequisites

Next.js 14+ with TypeScript
Supabase project
Supabase CLI installed
Basic TypeScript knowledge

Why Type Safety Matters

Without types:

// ❌ No type safety
const { data } = await supabase
  .from('posts')
  .select('*')

// data is any - no autocomplete, no type checking
console.log(data[0].titl) // Typo not caught!

With types:

// ✅ Full type safety
const { data } = await supabase
  .from('posts')
  .select('*')

// data is Post[] - autocomplete works, typos caught
console.log(data[0].title) // ✓
console.log(data[0].titl) // Error: Property 'titl' does not exist

Generating Database Types

Generate TypeScript types from your database schema:

npx supabase gen types typescript --project-id your-project-id > types/database.types.ts

Or from local database:

npx supabase gen types typescript --local > types/database.types.ts

This creates:

// types/database.types.ts
export type Json =
  | string
  | number
  | boolean
  | null
  | { [key: string]: Json | undefined }
  | Json[]

export interface Database {
  public: {
    Tables: {
      posts: {
        Row: {
          id: string
          title: string
          content: string | null
          user_id: string
          published: boolean
          created_at: string
          updated_at: string
        }
        Insert: {
          id?: string
          title: string
          content?: string | null
          user_id: string
          published?: boolean
          created_at?: string
          updated_at?: string
        }
        Update: {
          id?: string
          title?: string
          content?: string | null
          user_id?: string
          published?: boolean
          created_at?: string
          updated_at?: string
        }
        Relationships: [
          {
            foreignKeyName: "posts_user_id_fkey"
            columns: ["user_id"]
            referencedRelation: "users"
            referencedColumns: ["id"]
          }
        ]
      }
      // ... other tables
    }
    Views: {
      // ... views
    }
    Functions: {
      // ... functions
    }
    Enums: {
      // ... enums
    }
  }
}

Three types per table:

Row: Data returned from SELECT
Insert: Data for INSERT operations
Update: Data for UPDATE operations

Type-Safe Supabase Client

Create a typed client:

// lib/supabase/client.ts
import { createBrowserClient } from '@supabase/ssr'
import type { Database } from '@/types/database.types'

export function createClient() {
  return createBrowserClient<Database>(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
  )
}

Server client:

// lib/supabase/server.ts
import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'
import type { Database } from '@/types/database.types'

export async function createClient() {
  const cookieStore = await cookies()

  return createServerClient<Database>(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        get(name: string) {
          return cookieStore.get(name)?.value
        },
      },
    }
  )
}

Now all queries are type-safe:

const supabase = createClient()

// ✅ Type-safe query
const { data } = await supabase
  .from('posts') // Autocomplete shows all tables
  .select('title, content, user_id') // Autocomplete shows all columns
  .eq('published', true) // Type-checked

// data is inferred as:
// { title: string; content: string | null; user_id: string }[]

Type-Safe Queries

Basic Queries

// Select all columns
const { data: posts } = await supabase
  .from('posts')
  .select('*')

// posts: Database['public']['Tables']['posts']['Row'][]

// Select specific columns
const { data: titles } = await supabase
  .from('posts')
  .select('id, title')

// titles: { id: string; title: string }[]

// With filters
const { data: published } = await supabase
  .from('posts')
  .select('*')
  .eq('published', true)
  .order('created_at', { ascending: false })

// published: Database['public']['Tables']['posts']['Row'][]

Joins

// Join with profiles
const { data: postsWithAuthors } = await supabase
  .from('posts')
  .select(`
    *,
    profiles (
      name,
      avatar_url
    )
  `)

// Type inferred:
// {
//   ...Post,
//   profiles: {
//     name: string
//     avatar_url: string | null
//   } | null
// }[]

Insert

const { data: newPost, error } = await supabase
  .from('posts')
  .insert({
    title: 'My Post',
    content: 'Content here',
    user_id: userId,
    // published is optional (has default)
  })
  .select()
  .single()

// newPost: Database['public']['Tables']['posts']['Row']

// ❌ Type error - missing required field
await supabase.from('posts').insert({
  title: 'My Post'
  // Error: Property 'user_id' is missing
})

// ❌ Type error - wrong type
await supabase.from('posts').insert({
  title: 123 // Error: Type 'number' is not assignable to type 'string'
})

Update

const { data: updated } = await supabase
  .from('posts')
  .update({
    title: 'Updated Title',
    // All fields optional in Update type
  })
  .eq('id', postId)
  .select()
  .single()

// updated: Database['public']['Tables']['posts']['Row']

Delete

const { error } = await supabase
  .from('posts')
  .delete()
  .eq('id', postId)

Helper Types

Extract types for use in your application:

// types/index.ts
import type { Database } from './database.types'

// Table row types
export type Post = Database['public']['Tables']['posts']['Row']
export type Profile = Database['public']['Tables']['profiles']['Row']
export type Comment = Database['public']['Tables']['comments']['Row']

// Insert types
export type PostInsert = Database['public']['Tables']['posts']['Insert']
export type ProfileInsert = Database['public']['Tables']['profiles']['Insert']

// Update types
export type PostUpdate = Database['public']['Tables']['posts']['Update']

// Join types
export type PostWithAuthor = Post & {
  profiles: Pick<Profile, 'name' | 'avatar_url'> | null
}

export type PostWithComments = Post & {
  comments: Comment[]
}

Use in components:

// components/PostCard.tsx
import type { Post } from '@/types'

export function PostCard({ post }: { post: Post }) {
  return (
    <article>
      <h2>{post.title}</h2>
      <p>{post.content}</p>
    </article>
  )
}

Runtime Validation with Zod

TypeScript provides compile-time safety. Zod provides runtime validation:

npm install zod

Create schemas matching your database types:

// lib/validations/post.ts
import { z } from 'zod'

export const PostSchema = z.object({
  title: z.string().min(3).max(100),
  content: z.string().min(10).max(5000),
  published: z.boolean().default(false),
  user_id: z.string().uuid()
})

export const PostInsertSchema = PostSchema.omit({ user_id: true })

export const PostUpdateSchema = PostSchema.partial()

// Infer TypeScript types from Zod schemas
export type PostInput = z.infer<typeof PostInsertSchema>
export type PostUpdateInput = z.infer<typeof PostUpdateSchema>

Use in Server Actions:

// actions/posts.ts
'use server'

import { PostInsertSchema } from '@/lib/validations/post'
import { createClient } from '@/lib/supabase/server'

export async function createPost(formData: FormData) {
  // Parse and validate
  const result = PostInsertSchema.safeParse({
    title: formData.get('title'),
    content: formData.get('content'),
    published: formData.get('published') === 'on'
  })

  if (!result.success) {
    return {
      errors: result.error.flatten().fieldErrors
    }
  }

  const supabase = await createClient()
  const { data: { user } } = await supabase.auth.getUser()

  if (!user) {
    return { error: 'Unauthorized' }
  }

  const { data, error } = await supabase
    .from('posts')
    .insert({
      ...result.data,
      user_id: user.id
    })
    .select()
    .single()

  if (error) {
    return { error: error.message }
  }

  return { success: true, data }
}

Type-Safe Forms

Combine React Hook Form with Zod:

npm install react-hook-form @hookform/resolvers

// components/PostForm.tsx
'use client'

import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import { PostInsertSchema, type PostInput } from '@/lib/validations/post'

export function PostForm() {
  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting }
  } = useForm<PostInput>({
    resolver: zodResolver(PostInsertSchema)
  })

  async function onSubmit(data: PostInput) {
    const formData = new FormData()
    formData.append('title', data.title)
    formData.append('content', data.content)
    formData.append('published', String(data.published))

    await createPost(formData)
  }

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <div>
        <label htmlFor="title">Title</label>
        <input
          id="title"
          {...register('title')}
        />
        {errors.title && (
          <p className="text-red-500">{errors.title.message}</p>
        )}
      </div>

      <div>
        <label htmlFor="content">Content</label>
        <textarea
          id="content"
          {...register('content')}
        />
        {errors.content && (
          <p className="text-red-500">{errors.content.message}</p>
        )}
      </div>

      <div>
        <label>
          <input type="checkbox" {...register('published')} />
          Publish immediately
        </label>
      </div>

      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? 'Creating...' : 'Create Post'}
      </button>
    </form>
  )
}

Type-Safe RPC Calls

Generate types for Postgres functions:

-- Database function
CREATE FUNCTION get_user_stats(user_id UUID)
RETURNS JSON
LANGUAGE plpgsql
AS $$
BEGIN
  RETURN json_build_object(
    'post_count', (SELECT COUNT(*) FROM posts WHERE posts.user_id = get_user_stats.user_id),
    'comment_count', (SELECT COUNT(*) FROM comments WHERE comments.user_id = get_user_stats.user_id)
  );
END;
$$;

After regenerating types:

const { data } = await supabase
  .rpc('get_user_stats', { user_id: userId })

// data is typed based on function return type

For complex return types, define manually:

// types/index.ts
export type UserStats = {
  post_count: number
  comment_count: number
}

// Usage
const { data } = await supabase
  .rpc('get_user_stats', { user_id: userId })

const stats = data as UserStats

Type-Safe Realtime

Type realtime subscriptions:

'use client'

import { useEffect, useState } from 'react'
import { createClient } from '@/lib/supabase/client'
import type { Post } from '@/types'

export function RealtimePosts() {
  const [posts, setPosts] = useState<Post[]>([])
  const supabase = createClient()

  useEffect(() => {
    const channel = supabase
      .channel('posts')
      .on<Post>(
        'postgres_changes',
        {
          event: 'INSERT',
          schema: 'public',
          table: 'posts'
        },
        (payload) => {
          // payload.new is typed as Post
          setPosts(current => [payload.new, ...current])
        }
      )
      .subscribe()

    return () => {
      supabase.removeChannel(channel)
    }
  }, [supabase])

  return (
    <div>
      {posts.map(post => (
        <article key={post.id}>
          <h2>{post.title}</h2>
        </article>
      ))}
    </div>
  )
}

Enum Types

Define enums in database:

CREATE TYPE post_status AS ENUM ('draft', 'published', 'archived');

ALTER TABLE posts
ADD COLUMN status post_status DEFAULT 'draft';

Generated types include enums:

// types/database.types.ts
export interface Database {
  public: {
    Enums: {
      post_status: 'draft' | 'published' | 'archived'
    }
  }
}

Use in your code:

import type { Database } from '@/types/database.types'

type PostStatus = Database['public']['Enums']['post_status']

const status: PostStatus = 'published' // ✓
const invalid: PostStatus = 'pending' // Error

Automating Type Generation

Regenerate types after schema changes:

// package.json
{
  "scripts": {
    "types:generate": "npx supabase gen types typescript --local > types/database.types.ts",
    "types:generate:remote": "npx supabase gen types typescript --project-id your-project-id > types/database.types.ts"
  }
}

Run after migrations:

npx supabase db reset
npm run types:generate

Or use a git hook:

# .husky/post-merge
#!/bin/sh
if git diff-tree -r --name-only --no-commit-id ORIG_HEAD HEAD | grep --quiet "supabase/migrations"
then
  npm run types:generate
fi

Common Pitfalls

1. Not Regenerating Types

// ❌ Added column to database but didn't regenerate types
const { data } = await supabase
  .from('posts')
  .select('*')

console.log(data[0].new_column) // No autocomplete, no type checking

Always regenerate after schema changes.

2. Using `any` Types

// ❌ Losing type safety
const data: any = await supabase.from('posts').select('*')

// ✅ Keep types
const { data } = await supabase.from('posts').select('*')

3. Not Validating User Input

// ❌ No runtime validation
export async function createPost(data: any) {
  await supabase.from('posts').insert(data)
}

// ✅ Validate with Zod
export async function createPost(data: unknown) {
  const validated = PostSchema.parse(data)
  await supabase.from('posts').insert(validated)
}

4. Incorrect Type Assertions

// ❌ Unsafe assertion
const post = data as Post

// ✅ Validate first
const post = PostSchema.parse(data)

Advanced Patterns

Generic Query Builder

// lib/queries.ts
import type { Database } from '@/types/database.types'

type Tables = Database['public']['Tables']
type TableName = keyof Tables

export async function findById<T extends TableName>(
  supabase: SupabaseClient<Database>,
  table: T,
  id: string
): Promise<Tables[T]['Row'] | null> {
  const { data } = await supabase
    .from(table)
    .select('*')
    .eq('id', id)
    .single()

  return data
}

// Usage
const post = await findById(supabase, 'posts', postId)
// post is typed as Post | null

Type-Safe Query Filters

type QueryFilter<T> = {
  [K in keyof T]?: T[K] | { operator: 'eq' | 'neq' | 'gt' | 'lt'; value: T[K] }
}

export async function findWhere<T extends TableName>(
  supabase: SupabaseClient<Database>,
  table: T,
  filters: QueryFilter<Tables[T]['Row']>
): Promise<Tables[T]['Row'][]> {
  let query = supabase.from(table).select('*')

  for (const [key, value] of Object.entries(filters)) {
    if (typeof value === 'object' && 'operator' in value) {
      query = query[value.operator](key, value.value)
    } else {
      query = query.eq(key, value)
    }
  }

  const { data } = await query
  return data || []
}

// Usage
const posts = await findWhere(supabase, 'posts', {
  published: true,
  view_count: { operator: 'gt', value: 100 }
})

Summary

Complete type safety in Next.js with Supabase requires:

Generate TypeScript types from database schema
Use typed Supabase clients
Validate user input with Zod at runtime
Regenerate types after schema changes
Combine TypeScript and Zod for compile-time and runtime safety

This approach catches errors early, provides excellent developer experience with autocomplete, and prevents invalid data from reaching your database.

[INTERNAL LINK: nextjs-server-actions-supabase-complete-guide]
[INTERNAL LINK: nextjs-supabase-database-design-optimization]
[INTERNAL LINK: supabase-postgres-functions-triggers-guide]

Originally published at https://www.iloveblogs.blog

DEV Community

Complete Type Safety Guide for Next.js and Supabase with TypeScript

Complete Type Safety Guide for Next.js and Supabase with TypeScript

Prerequisites

Why Type Safety Matters

Generating Database Types

Type-Safe Supabase Client

Type-Safe Queries

Basic Queries

Joins

Insert

Update

Delete

Helper Types

Runtime Validation with Zod

Type-Safe Forms

Type-Safe RPC Calls

Type-Safe Realtime

Enum Types

Automating Type Generation

Common Pitfalls

1. Not Regenerating Types

2. Using `any` Types

3. Not Validating User Input

4. Incorrect Type Assertions

Advanced Patterns

Generic Query Builder

Type-Safe Query Filters

Summary

Top comments (0)

Complete Type Safety Guide for Next.js and Supabase with TypeScript

Prerequisites

Why Type Safety Matters

Generating Database Types

Type-Safe Supabase Client

Type-Safe Queries

Basic Queries

Joins

Insert

Update

Delete

Helper Types

Runtime Validation with Zod

Type-Safe Forms

Type-Safe RPC Calls

Type-Safe Realtime

Enum Types

Automating Type Generation

Common Pitfalls

1. Not Regenerating Types

2. Using any Types

3. Not Validating User Input

4. Incorrect Type Assertions

Advanced Patterns

Generic Query Builder

Type-Safe Query Filters

Summary

2. Using `any` Types