Skip to Content
FrameworksNext.js

Next.js Integration

Use Synap SDK in your Next.js applications with App Router or Pages Router.

Installation

npm install @synap/sdk

Setup

Environment Variables

Create .env.local:

.env.local
SYNAP_URL=https://api.synap.app
SYNAP_API_KEY=sk_your_key_here

Server Components

Use SDK directly in Server Components:

app/tasks/page.tsx
import { SynapSDK } from '@synap/sdk'
 
const synap = new SynapSDK({
  url: process.env.SYNAP_URL!,
  apiKey: process.env.SYNAP_API_KEY!
})
 
export default async function TasksPage() {
  const tasks = await synap.entities.list({ type: 'task' })
 
  return (
    <div>
      <h1>Tasks</h1>
      <ul>
        {tasks.map(task => (
          <li key={task.id}>{task.title}</li>
        ))}
      </ul>
    </div>
  )
}

Client Components

Create an API route for client-side requests:

app/api/tasks/route.ts
import { SynapSDK } from '@synap/sdk'
import { NextResponse } from 'next/server'
 
const synap = new SynapSDK({
  url: process.env.SYNAP_URL!,
  apiKey: process.env.SYNAP_API_KEY!
})
 
export async function GET() {
  const tasks = await synap.entities.list({ type: 'task' })
  return NextResponse.json(tasks)
}
 
export async function POST(request: Request) {
  const body = await request.json()
  
  const { entityId } = await synap.entities.create({
    type: 'task',
    title: body.title,
    metadata: body.metadata
  })
  
  return NextResponse.json({ entityId })
}

Then use it in your client component:

app/tasks/create-task.tsx
'use client'
 
import { useState } from 'react'
 
export function CreateTask() {
  const [title, setTitle] = useState('')
 
  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault()
    
    const response = await fetch('/api/tasks', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ title })
    })
    
    const { entityId } = await response.json()
    console.log('Created:', entityId)
    setTitle('')
  }
 
  return (
    <form onSubmit={handleSubmit}>
      <input
        value={title}
        onChange={(e) => setTitle(e.target.value)}
        placeholder="Task title"
      />
      <button type="submit">Create Task</button>
    </form>
  )
}

Pages Router

API Route

pages/api/tasks/[id].ts
import { SynapSDK } from '@synap/sdk'
import type { NextApiRequest, NextApiResponse } from 'next'
 
const synap = new SynapSDK({
  url: process.env.SYNAP_URL!,
  apiKey: process.env.SYNAP_API_KEY!
})
 
export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const { id } = req.query
 
  if (req.method === 'GET') {
    const entity = await synap.entities.get(id as string)
    return res.json(entity)
  }
 
  if (req.method === 'PUT') {
    await synap.entities.update(id as string, req.body)
    return res.json({ success: true })
  }
 
  res.status(405).json({ error: 'Method not allowed' })
}

Server-Side Rendering

pages/tasks/index.tsx
import { SynapSDK } from '@synap/sdk'
import type { GetServerSideProps } from 'next'
 
export const getServerSideProps: GetServerSideProps = async () => {
  const synap = new SynapSDK({
    url: process.env.SYNAP_URL!,
    apiKey: process.env.SYNAP_API_KEY!
  })
 
  const tasks = await synap.entities.list({ type: 'task' })
 
  return {
    props: { tasks }
  }
}
 
export default function TasksPage({ tasks }) {
  return (
    <div>
      <h1>Tasks</h1>
      <ul>
        {tasks.map(task => (
          <li key={task.id}>{task.title}</li>
        ))}
      </ul>
    </div>
  )
}

Best Practices

Singleton SDK Instance

Create a single SDK instance:

lib/synap.ts
import { SynapSDK } from '@synap/sdk'
 
export const synap = new SynapSDK({
  url: process.env.SYNAP_URL!,
  apiKey: process.env.SYNAP_API_KEY!
})

Import it everywhere:

import { synap } from '@/lib/synap'

Error Handling

app/api/tasks/route.ts
import { synap } from '@/lib/synap'
import { NextResponse } from 'next/server'
 
export async function GET() {
  try {
    const tasks = await synap.entities.list({ type: 'task' })
    return NextResponse.json(tasks)
  } catch (error) {
    console.error('Failed to fetch tasks:', error)
    return NextResponse.json(
      { error: 'Failed to fetch tasks' },
      { status: 500 }
    )
  }
}

TypeScript

Enable strict mode in tsconfig.json:

{
  "compilerOptions": {
    "strict": true
  }
}

The SDK is fully typed:

import type { Entity, EntityType } from '@synap/sdk'
 
const entity: Entity<'task'> = await synap.entities.get(id)
// entity.metadata is typed based on 'task' type

Examples

Full CRUD Example

app/api/tasks/route.ts
import { synap } from '@/lib/synap'
import { NextResponse } from 'next/server'
 
// List
export async function GET() {
  const tasks = await synap.entities.list({
    type: 'task',
    limit: 50
  })
  return NextResponse.json(tasks)
}
 
// Create
export async function POST(request: Request) {
  const body = await request.json()
  
  const { entityId } = await synap.entities.create({
    type: 'task',
    title: body.title,
    metadata: {
      priority: body.priority,
      dueDate: body.dueDate
    }
  })
  
  return NextResponse.json({ entityId })
}
app/api/tasks/[id]/route.ts
import { synap } from '@/lib/synap'
import { NextResponse } from 'next/server'
 
// Get
export async function GET(
  request: Request,
  { params }: { params: { id: string } }
) {
  const entity = await synap.entities.get(params.id)
  return NextResponse.json(entity)
}
 
// Update
export async function PUT(
  request: Request,
  { params }: { params: { id: string } }
) {
  const body = await request.json()
  await synap.entities.update(params.id, body)
  return NextResponse.json({ success: true })
}
 
// Delete
export async function DELETE(
  request: Request,
  { params }: { params: { id: string } }
) {
  await synap.entities.delete(params.id)
  return NextResponse.json({ success: true })
}

Next Steps

Last updated on
Events APITask Manager