How to Integrate Bolt.new with TYPO3

TYPO3 does not include a headless JSON API out of the box — you must install the EXT:headless extension developed by TYPO3 agency Macopedia and maintained by the Friends of TYPO3 organization. On your TYPO3 server, run the Composer command to install the extension: composer require friendsoftypo3/headless. After installation, activate the extension in the TYPO3 backend under Admin Tools → Extensions. The extension adds a new site configuration option called 'headless' that you need to enable in your site configuration file (typically located at config/sites/your-site/config.yaml). Add headless: true under the root site configuration block. Once activated, TYPO3 Headless responds to requests with a type parameter of 834 — for example, https://your-typo3.com/?type=834 returns the homepage content as JSON. You can verify the API is working by opening that URL in your browser and checking that it returns a JSON object with page and content data rather than HTML. The extension also respects TYPO3's existing page access settings and caching configuration — cached responses are automatically invalidated when editors publish new content in the TYPO3 backend. For TYPO3 12+, the modern PSR-15 middleware approach is the default and provides faster response times than the legacy type-parameter approach used in older versions.

1# config/sites/main/config.yaml — add headless: true
2base: 'https://your-typo3.com/'
3baseVariants: []
4errorHandling: []
5headless: true
6languages:
7  -
8    base: /
9    enabled: true
10    languageId: 0
11    locale: en_US.UTF-8
12    title: English
13rootPageId: 1
14websiteTitle: 'My TYPO3 Site'
15
16# Verify the API works by opening in browser:
17# https://your-typo3.com/?type=834
18# Expected: JSON object with page title, content array, metadata

With TYPO3 Headless configured and responding with JSON, the next step is building the server-side proxy in your Bolt.new project. A proxy API route is essential for two reasons: first, TYPO3 installations often do not include CORS headers for browser requests originating from a different domain, which would cause direct client-side fetch calls to fail in Bolt's preview; second, any authentication tokens or credentials for accessing restricted content must remain server-side and never be exposed in client-side code. In your Bolt.new project, create a .env file at the project root. Add TYPO3_API_URL set to your TYPO3 site's base URL (for example, https://your-typo3.com). If your TYPO3 site requires an API token for accessing certain pages or frontend user groups, also add TYPO3_API_TOKEN. Keep in mind that Bolt's WebContainer environment means that all API calls go outbound from the browser-based Node.js runtime — outbound HTTP calls to your TYPO3 server work correctly in the Bolt preview, so you can test and iterate on the integration before deploying. Once you have the .env file ready, use the Bolt chat prompt below to generate the main TYPO3 API route. After Bolt generates the code, review that it reads TYPO3_API_URL from process.env without a NEXT_PUBLIC_ prefix (keeping it server-side only) and that the request includes the type=834 parameter required by the TYPO3 Headless extension.

1// app/api/typo3/page/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4export async function GET(request: NextRequest) {
5  const apiUrl = process.env.TYPO3_API_URL;
6  if (!apiUrl) {
7    return NextResponse.json(
8      { error: 'TYPO3_API_URL is not configured' },
9      { status: 500 }
10    );
11  }
12
13  const { searchParams } = new URL(request.url);
14  const slug = searchParams.get('slug') || '/';
15
16  const typo3Url = new URL(apiUrl);
17  typo3Url.searchParams.set('type', '834');
18  typo3Url.searchParams.set('tx_headless_page[action]', 'page');
19  typo3Url.searchParams.set('tx_headless_page[controller]', 'Page');
20  typo3Url.searchParams.set('tx_headless_page[slug]', slug);
21
22  const headers: Record<string, string> = {
23    'Accept': 'application/json',
24  };
25
26  if (process.env.TYPO3_API_TOKEN) {
27    headers['Authorization'] = `Bearer ${process.env.TYPO3_API_TOKEN}`;
28  }
29
30  try {
31    const response = await fetch(typo3Url.toString(), { headers });
32
33    if (!response.ok) {
34      return NextResponse.json(
35        { error: `TYPO3 API error: ${response.status} ${response.statusText}` },
36        { status: response.status }
37      );
38    }
39
40    const data = await response.json();
41    return NextResponse.json(data);
42  } catch (error) {
43    const message = error instanceof Error ? error.message : 'Unknown error';
44    return NextResponse.json({ error: message }, { status: 500 });
45  }
46}

TYPO3 content is structured differently from a simple blog CMS. Each page contains a 'colPos' system (content columns) and an array of content elements, where each element has a 'type' field (such as textmedia, textpic, bullets, table, shortcut, menu_sitemap, and custom types from installed extensions). Your React frontend needs a content renderer component that maps each TYPO3 content type to a React component. This is the core architectural piece of a TYPO3 headless frontend. For a minimum viable implementation, handle the most common types: text (plain HTML content), textmedia (text with images), bullets (unordered/ordered lists), header (standalone headings), and table. For types your renderer does not recognize, render a fallback that shows the content type name so you can identify gaps during development. TYPO3 Headless returns richtext HTML in a property called bodytext — render it using dangerouslySetInnerHTML, which is safe here because the content comes from your own trusted TYPO3 installation and is sanitized by TYPO3's built-in HTMLparser. Image data in textmedia elements includes publicUrl for the file path, which is relative to your TYPO3 domain — prepend TYPO3_API_URL to construct the full URL. Once the content renderer is working, build a catch-all route at app/[...slug]/page.tsx that fetches from /api/typo3/page with the current URL slug and passes the response to the content renderer.

1// components/TYPO3ContentRenderer.tsx
2'use client';
3
4interface TYPO3ContentElement {
5  type: string;
6  uid: number;
7  pid: number;
8  header?: string;
9  bodytext?: string;
10  bullets?: string[];
11  media?: Array<{
12    publicUrl: string;
13    properties: { title: string; alternative: string };
14  }>;
15  [key: string]: unknown;
16}
17
18interface Props {
19  content: TYPO3ContentElement[];
20  baseUrl: string;
21}
22
23export function TYPO3ContentRenderer({ content, baseUrl }: Props) {
24  return (
25    <div className="space-y-8">
26      {content.map((element) => (
27        <div key={element.uid}>
28          {renderElement(element, baseUrl)}
29        </div>
30      ))}
31    </div>
32  );
33}
34
35function renderElement(element: TYPO3ContentElement, baseUrl: string) {
36  switch (element.type) {
37    case 'text':
38    case 'textmedia':
39    case 'textpic':
40      return (
41        <div>
42          {element.header && (
43            <h2 className="text-2xl font-bold text-gray-900 mb-4">{element.header}</h2>
44          )}
45          {element.media && element.media.length > 0 && (
46            <img
47              src={`${baseUrl}${element.media[0].publicUrl}`}
48              alt={element.media[0].properties?.alternative || element.header || ''}
49              className="w-full rounded-lg mb-4 object-cover"
50            />
51          )}
52          {element.bodytext && (
53            <div
54              className="prose prose-lg max-w-none"
55              dangerouslySetInnerHTML={{ __html: element.bodytext }}
56            />
57          )}
58        </div>
59      );
60
61    case 'header':
62      return (
63        <h2 className="text-3xl font-bold text-gray-900">
64          {element.header}
65        </h2>
66      );
67
68    case 'bullets':
69      return (
70        <div>
71          {element.header && (
72            <h2 className="text-2xl font-bold text-gray-900 mb-3">{element.header}</h2>
73          )}
74          <ul className="list-disc list-inside space-y-2 text-gray-700">
75            {(element.bullets || []).map((item, i) => (
76              <li key={i}>{item}</li>
77            ))}
78          </ul>
79        </div>
80      );
81
82    default:
83      return (
84        <div className="p-4 bg-gray-50 rounded border border-gray-200 text-sm text-gray-400">
85          Unsupported content type: {element.type}
86        </div>
87      );
88  }
89}

TYPO3's multi-language support is one of its most powerful enterprise features, and the Headless extension passes language configuration through to the JSON response. In a TYPO3 site, each language has a unique languageId (0 for the default language, 1, 2, 3 for additional languages) and a base path (such as /en/, /de/, /fr/). The Headless API exposes the list of configured site languages in a siteLanguages endpoint, which your frontend can use to generate language switcher links. To request content in a specific language, the standard approach is to pass the language's base path as part of the URL — TYPO3 determines the language from the URL prefix based on your site configuration. Alternatively, some setups use an Accept-Language header or a languageId query parameter. Check your specific TYPO3 site configuration to confirm which approach is configured. The React language switcher component should read the available languages from the TYPO3 API and render links to the equivalent page in each language. TYPO3 handles language fallbacks automatically — if a translation does not exist, it falls back to the default language content based on the configured fallback type. One important note: the language-specific page URLs in TYPO3 are managed in the TYPO3 backend and cannot be changed from the Bolt frontend. Content editors add and manage translations entirely within the TYPO3 backend editorial workflow.

1// app/api/typo3/languages/route.ts
2import { NextResponse } from 'next/server';
3
4export async function GET() {
5  const apiUrl = process.env.TYPO3_API_URL;
6  if (!apiUrl) {
7    return NextResponse.json({ error: 'TYPO3_API_URL not configured' }, { status: 500 });
8  }
9
10  const url = new URL(apiUrl);
11  url.searchParams.set('type', '834');
12  url.searchParams.set('tx_headless_page[action]', 'languages');
13  url.searchParams.set('tx_headless_page[controller]', 'Page');
14
15  try {
16    const response = await fetch(url.toString(), {
17      headers: { 'Accept': 'application/json' },
18    });
19
20    if (!response.ok) {
21      return NextResponse.json(
22        { error: `TYPO3 languages API error: ${response.status}` },
23        { status: response.status }
24      );
25    }
26
27    const data = await response.json();
28    // TYPO3 Headless returns languages in data.siteLanguages or data.languages
29    const languages = data.siteLanguages || data.languages || [];
30    return NextResponse.json({ languages });
31  } catch (error) {
32    const message = error instanceof Error ? error.message : 'Unknown error';
33    return NextResponse.json({ error: message }, { status: 500 });
34  }
35}

Your TYPO3 Headless frontend works in Bolt's WebContainer preview because all TYPO3 API calls are outbound HTTP requests from the server-side API routes — outbound calls to external servers work correctly in the WebContainer development environment. When you are ready to deploy for public access, connect your Bolt project to Netlify through Settings → Applications → Netlify → Connect. Bolt will build the Next.js project and deploy it to a *.netlify.app URL. After the initial deployment, go to your Netlify dashboard → Site Configuration → Environment Variables and add TYPO3_API_URL (your full TYPO3 site URL) and TYPO3_API_TOKEN if you are using authentication. Trigger a redeploy from the Netlify dashboard for the variables to take effect. One critical WebContainer limitation to understand: incoming webhooks from TYPO3 cannot reach the Bolt preview URL. Bolt's WebContainer runs inside a browser tab and does not expose a public-facing HTTP server, so TYPO3 cache invalidation hooks, workflow notifications, and editorial callbacks all require your deployed Netlify URL. After deployment, configure any TYPO3 extension webhooks or cache-invalidation hooks to point at your Netlify URL. If you are using Next.js on-demand revalidation to keep content fresh after TYPO3 publishes, build a revalidation endpoint that accepts a POST request with a secret token, calls revalidatePath for the affected pages, and configure TYPO3 to call this endpoint on page publish using the TYPO3 Headless extension's built-in cache invalidation hooks.

1// app/api/typo3/revalidate/route.ts
2import { NextResponse } from 'next/server';
3import { revalidatePath } from 'next/cache';
4
5export async function POST(request: Request) {
6  const authHeader = request.headers.get('authorization');
7  const secret = authHeader?.replace('Bearer ', '');
8
9  if (!secret || secret !== process.env.TYPO3_REVALIDATE_SECRET) {
10    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
11  }
12
13  try {
14    const body = await request.json();
15    const slug = body?.slug as string | undefined;
16
17    // Always revalidate the root page
18    revalidatePath('/');
19
20    // Revalidate the specific slug if provided
21    if (slug) {
22      const cleanSlug = slug.startsWith('/') ? slug : `/${slug}`;
23      revalidatePath(cleanSlug);
24    }
25
26    return NextResponse.json({ revalidated: true, slug: slug || '/' });
27  } catch {
28    return NextResponse.json({ error: 'Revalidation failed' }, { status: 500 });
29  }
30}