Your app.Our runtime.

Built for React that grows —

pages first, then APIs,

auth, and agents without

leaving the same project.

02 / Runtime

One directory.Full stack.

Copythecommandtogetstarted

Pages

app/

APIs

route.ts

Auth

sessions

Agents

stream

Typed procedures

createCaller
rsc → api
same app/

Runtime

SSR / RSC
middleware
one process

AI layer

vista/ai
tools + RAG
g agent

Same app.Same request.

Edit a route, hit Run, and read the JSON. Pages and handlers share one app/ tree — no second service folder for a route that only your UI needs.

Before

Separate frontend & backend

UI and API live in different projects. Run simulates the remote fetch.

frontend/src/pages/notes.tsx

// Separate frontend — must reach another origin
const res = await fetch('https://api.example.com/notes')
if (!res.ok) throw new Error('backend unreachable')
const notes = await res.json()
return notes

Response

idle

// Edit a file, then Run to see the response.

After

Vista — one app/

Pages and routes share one directory. Edit a file and run it here.

app/api/notes/route.ts

export async function GET() {
  return Response.json({
    notes: [
      { id: 'n1', title: 'Ship notes API' },
      { id: 'n2', title: 'Same app/ tree' },
    ],
  })
}

export async function POST() {
  return Response.json(
    { note: { id: 'n3', title: 'Created in-process' } },
    { status: 201 }
  )
}

Response

idle

// Edit a file, then Run to see the response.

Auth that ships.Fail closed.

vista g auth writes providers, sign-in, and middleware that denies /account without a session — not a package you bolt on later.

auth.ts

Auth

import VistaAuth, { Credentials, GitHub, Google } from 'vista/auth'

export const { handlers, auth, signIn, signOut, authMiddleware } = VistaAuth({
  pages: { signIn: '/signin' },
  providers: [
    GitHub({}),
    Google({}),
    Credentials({
      authorize: async (credentials) => {
        if (!credentials.email || !credentials.password) return null
        return {
          id: credentials.email,
          email: credentials.email,
          name: credentials.email,
        }
      },
    }),
  ],
})

same app/

import { authMiddleware } from './auth'

export default authMiddleware(({ auth, request }) => {
  const pathname = new URL(request.url).pathname
  if (pathname.startsWith('/account') && !auth) {
    return false
  }
  return true
})

Decision

idle

// Edit auth or middleware, pick a path, then Run.

One agent.Same runtime.

Streaming agents and tools live beside your pages. Swap Groq, NIM, or OpenAI with one provider:model string — no second AI service.

app/agents/support/agent.ts

Agent

import { agent, tool } from 'vista/ai'

export const supportAgent = agent({
  name: 'support',
  model: 'openrouter:openai/gpt-4o-mini',
  systemPrompt: 'You help ship Vista apps.',
  tools: [
    tool({
      name: 'ping',
      description: 'Check connectivity',
      execute: async () => ({ ok: true }),
    }),
  ],
  memory: true,
})

same app/

import { supportAgent } from '../../../agents/support/agent'

export async function POST(req: Request) {
  const { prompt, sessionId } = await req.json()
  const stream = supportAgent.stream({
    prompt,
    sessionId,
  })
  return stream.toDataStreamResponse()
}

Stream

idle

// Edit the agent or route, enter a prompt, then Run.

Stay in one project as the product grows.

Vista is built for the path most apps actually take. You start with pages under app/. When you need a handler, it lives next to the screen that calls it. When you need a session, auth and fail-closed middleware ship from the same scaffold. When you need a model in the loop, agents and tools run on that same runtime — one provider:model string, not a second service folder.

The point is not to replace every tool you already know. It is to keep UI, APIs, auth, and AI in one directory so the request path stays obvious: edit a file, run it, ship it. Typed procedures, route handlers, and streaming agents share the process your React tree already lives in.

If you are still deciding where the backend should sit, start here. Create the app, grow the tree, and move a contract out later only when the product asks for it — not because the framework forced a split on day one.