How to Integrate Bolt.new with Vimeo

Vimeo's API has two usage patterns with different authentication requirements. Understanding the difference helps you choose the right approach for your use case. The OEmbed pattern requires no credentials at all. Send a GET request to `https://vimeo.com/api/oembed.json?url=https://vimeo.com/YOUR_VIDEO_ID` and receive JSON with the complete embed code, thumbnail URL, video title, author name, and dimensions. This is public and works from any client or server — perfect for embedding known public videos without setting up API keys. The REST API pattern requires a personal access token for private videos, user-specific data, and higher rate limits. Go to developer.vimeo.com, log in, and create an app. Under 'Personal Access Tokens', generate a token with the scopes you need: `public` (public videos), `private` (private videos), `video_files` (direct video file URLs for download), and `interact` (likes, comments). The token is a long string starting with a series of numbers — copy it immediately as you cannot view it again after the page closes. Your Vimeo user ID is the number in your profile URL (`vimeo.com/USER_ID`). You can also find it by calling `api.vimeo.com/me` with your token. Add both to your .env.local file. Do not commit these to version control. Note on rate limits: unauthenticated OEmbed calls are limited per IP. Authenticated API calls have higher limits (1,000 requests per minute on Pro plans). For high-traffic apps, cache API responses rather than fetching fresh data on every page load.

1// lib/vimeo.ts
2const VIMEO_API_BASE = 'https://api.vimeo.com';
3
4export interface VimeoVideo {
5  uri: string;
6  name: string;
7  description: string | null;
8  duration: number;
9  width: number;
10  height: number;
11  created_time: string;
12  stats: { plays: number };
13  pictures: {
14    sizes: Array<{ width: number; height: number; link: string; link_with_play_button: string }>;
15  };
16  embed: { html: string };
17  link: string;
18}
19
20export interface VimeoCollection {
21  total: number;
22  page: number;
23  per_page: number;
24  paging: { next: string | null; previous: string | null };
25  data: VimeoVideo[];
26}
27
28export async function vimeoFetch<T>(path: string): Promise<T> {
29  const token = process.env.VIMEO_ACCESS_TOKEN;
30  if (!token) throw new Error('VIMEO_ACCESS_TOKEN is not set');
31
32  const url = path.startsWith('http') ? path : `${VIMEO_API_BASE}${path}`;
33  const response = await fetch(url, {
34    headers: {
35      'Authorization': `Bearer ${token}`,
36      'Accept': 'application/vnd.vimeo.*+json;version=3.4',
37      'Content-Type': 'application/json',
38    },
39    next: { revalidate: 300 }, // Cache for 5 minutes in Next.js
40  });
41
42  if (response.status === 401) {
43    throw new Error('Invalid Vimeo access token');
44  }
45  if (response.status === 404) {
46    throw new Error('Vimeo resource not found');
47  }
48  if (!response.ok) {
49    const error = await response.json().catch(() => ({ error: 'Unknown error' }));
50    throw new Error(error.error ?? `Vimeo API error: ${response.status}`);
51  }
52
53  return response.json();
54}
55
56export function getThumbnail(video: VimeoVideo, preferredWidth = 640): string {
57  const sizes = video.pictures.sizes;
58  const closest = sizes.reduce((prev, curr) =>
59    Math.abs(curr.width - preferredWidth) < Math.abs(prev.width - preferredWidth) ? curr : prev
60  );
61  return closest.link_with_play_button ?? closest.link;
62}
63
64export function formatDuration(seconds: number): string {
65  const m = Math.floor(seconds / 60);
66  const s = seconds % 60;
67  return `${m}:${s.toString().padStart(2, '0')}`;
68}

The OEmbed approach is the fastest way to embed Vimeo videos in your Bolt app. Create a Next.js API route that proxies OEmbed requests to avoid browser CORS restrictions on direct client-side calls. The Vimeo OEmbed endpoint supports useful parameters: `width` and `height` to constrain embed dimensions, `autoplay=1` to start playing on load, `loop=1` for looping, and `title=0` to hide the video title overlay. The OEmbed response contains a complete iframe embed code in the `html` field. You can render this directly using `dangerouslySetInnerHTML` in React — this is safe because the HTML comes from Vimeo's trusted OEmbed endpoint, not user input. The response also includes the thumbnail URL, video title, author name, and the original video dimensions which you need to calculate the aspect ratio. For responsive embeds, do not use the hardcoded width and height from the iframe HTML. Instead, wrap the embed in a container div with `padding-bottom: 56.25%` (for 16:9) and `position: relative`, then set the iframe to `position: absolute; inset: 0; width: 100%; height: 100%`. This technique (the intrinsic ratio trick) makes the embed scale with the container without JavaScript. For performance, avoid calling OEmbed on every page render. If you know the Vimeo video IDs in advance, pre-fetch the OEmbed data at build time using Next.js static generation and cache the results.

1// app/api/vimeo/oembed/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4export async function GET(request: NextRequest) {
5  const videoUrl = request.nextUrl.searchParams.get('url');
6
7  if (!videoUrl || !videoUrl.includes('vimeo.com')) {
8    return NextResponse.json({ error: 'Valid Vimeo URL required' }, { status: 400 });
9  }
10
11  const oembedUrl = new URL('https://vimeo.com/api/oembed.json');
12  oembedUrl.searchParams.set('url', videoUrl);
13  oembedUrl.searchParams.set('width', '1280');
14  oembedUrl.searchParams.set('responsive', 'true');
15
16  const response = await fetch(oembedUrl.toString(), {
17    next: { revalidate: 3600 }, // Cache OEmbed responses for 1 hour
18  });
19
20  if (!response.ok) {
21    return NextResponse.json(
22      { error: 'Video not found or not embeddable' },
23      { status: response.status }
24    );
25  }
26
27  const data = await response.json();
28  return NextResponse.json(data);
29}
30
31// app/components/VimeoEmbed.tsx
32'use client';
33import { useState, useEffect } from 'react';
34
35interface OEmbedData {
36  html: string;
37  title: string;
38  thumbnail_url: string;
39  width: number;
40  height: number;
41  author_name: string;
42}
43
44export function VimeoEmbed({ vimeoUrl, className = '' }: { vimeoUrl: string; className?: string }) {
45  const [oembed, setOembed] = useState<OEmbedData | null>(null);
46  const [loading, setLoading] = useState(true);
47  const [error, setError] = useState(false);
48
49  useEffect(() => {
50    fetch(`/api/vimeo/oembed?url=${encodeURIComponent(vimeoUrl)}`)
51      .then(r => r.json())
52      .then(data => {
53        if (data.error) throw new Error(data.error);
54        setOembed(data);
55      })
56      .catch(() => setError(true))
57      .finally(() => setLoading(false));
58  }, [vimeoUrl]);
59
60  if (loading) return (
61    <div className={`bg-gray-900 animate-pulse rounded-lg aspect-video ${className}`} />
62  );
63
64  if (error || !oembed) return (
65    <div className={`bg-gray-900 rounded-lg aspect-video flex items-center justify-center ${className}`}>
66      <p className="text-gray-400 text-sm">Video unavailable</p>
67    </div>
68  );
69
70  return (
71    <div
72      className={`relative aspect-video rounded-lg overflow-hidden ${className}`}
73      dangerouslySetInnerHTML={{ __html: oembed.html }}
74    />
75  );
76}

Fetching a user's video library requires the authenticated REST API. The Vimeo API uses cursor-based pagination via the `paging.next` field in responses — when you have more videos than the per_page limit, `paging.next` contains a URL for the next page. Implement this pagination so your gallery can display large video collections. The key endpoint for fetching user videos is `GET /users/{user_id}/videos`. Add query parameters to control the response: `fields` to request only the data you need (reduces response size significantly), `per_page` for the page size (max 100), `page` for pagination, and `sort` with `date` or `plays` to control ordering. Using the `fields` parameter is crucial for performance. Without it, Vimeo returns all metadata for every video including file download URLs, review links, tags, and embed codes for every size. A response for 20 videos without field filtering can be 50-100KB. With `fields=uri,name,description,duration,pictures.sizes,stats.plays,embed.html,link`, the same response is under 10KB. For the gallery UI, display a 2-3 column responsive grid with thumbnail cards. Each card shows the thumbnail with a play button overlay, video title, duration, and view count. Clicking a card opens the full embed in a modal or navigates to a detail page. Add 'Load More' pagination rather than infinite scroll — it is simpler to implement and better for users on slower connections.

1// app/api/vimeo/videos/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { vimeoFetch, VimeoCollection } from '@/lib/vimeo';
4
5const FIELDS = [
6  'uri', 'name', 'description', 'duration', 'created_time',
7  'stats.plays', 'pictures.sizes', 'embed.html', 'link', 'width', 'height',
8].join(',');
9
10export async function GET(request: NextRequest) {
11  const page = request.nextUrl.searchParams.get('page') ?? '1';
12  const perPage = Math.min(
13    parseInt(request.nextUrl.searchParams.get('per_page') ?? '12'),
14    100
15  );
16  const userId = process.env.VIMEO_USER_ID;
17
18  if (!userId) {
19    return NextResponse.json({ error: 'VIMEO_USER_ID not configured' }, { status: 500 });
20  }
21
22  try {
23    const data = await vimeoFetch<VimeoCollection>(
24      `/users/${userId}/videos?fields=${FIELDS}&per_page=${perPage}&page=${page}&sort=date`
25    );
26    return NextResponse.json(data);
27  } catch (error) {
28    const message = error instanceof Error ? error.message : 'Unknown error';
29    return NextResponse.json({ error: message }, { status: 500 });
30  }
31}

The Vimeo integration is fully functional in Bolt.new's WebContainer for development — all outbound API calls to Vimeo's REST endpoint and OEmbed work in the preview. When you are ready for production, deploy to Netlify or Bolt Cloud. In Bolt.new, click the Deploy button and connect to Netlify via OAuth. Bolt will build your Next.js project and deploy it automatically. After the initial deployment, go to Netlify's dashboard → Site Configuration → Environment Variables and add `VIMEO_ACCESS_TOKEN` and `VIMEO_USER_ID`. Trigger a redeploy (Deploys → Trigger deploy) to make the variables available. One Bolt.new WebContainer limitation worth noting: for video uploads to Vimeo, the standard Vimeo upload flow requires reading large binary files from disk and streaming them to Vimeo's upload API. The WebContainer's ephemeral in-memory file system is not suitable for large file handling — files exist only in memory during the session and there is no persistent local storage. For video upload features, implement them after deployment where a real server environment can handle large file streams. Use multipart form data and stream the file directly to Vimeo's upload endpoint without reading the entire file into memory. For private videos, ensure your Vimeo access token has the `private` scope. Videos set to 'Only me' or 'Password protected' in Vimeo require this scope; otherwise the API returns 404 for those video IDs even when the correct token is provided.

1// netlify.toml
2[build]
3  command = "npm run build"
4  publish = ".next"
5
6[[plugins]]
7  package = "@netlify/plugin-nextjs"
8
9[build.environment]
10  NODE_VERSION = "20"
11
12# Cache Vimeo thumbnails aggressively
13[[headers]]
14  for = "/api/vimeo/*"
15  [headers.values]
16    Cache-Control = "s-maxage=300, stale-while-revalidate=60"