How to Integrate Vimeo with V0

Start by using V0 to generate the front-end video gallery component. Open your V0 project and describe the layout you want — a grid of video cards, a featured video section, or a list layout with thumbnails. Be specific about what data each card should show: thumbnail image, title, duration, view count, and an embed trigger. V0 will generate a React component with placeholder data that you'll connect to the real Vimeo API in the next step. A good V0 prompt describes the visual layout, the data shape, and the interactive behavior. For example, tell V0 you want a responsive grid of video cards where each card displays a thumbnail loaded from a URL prop, a title, a duration badge, and a view count. Specify that clicking a card should open a modal with an iframe-based Vimeo embed. V0 generates clean Tailwind-styled components — you can refine colors, spacing, and typography in V0's Design Mode without writing CSS. The generated component will use hardcoded placeholder data like thumbnail URLs and titles. That's exactly what you want at this stage — you're designing the structure first, then wiring up live data. Once V0 generates the component, review it in the preview pane and use follow-up prompts to adjust any layout details before moving to the API route step.

Now create a Next.js API route that proxies requests to the Vimeo API. This route uses your server-side access token (stored as an environment variable) to fetch video data, and returns it to the client component without ever exposing your credentials. Create a file at app/api/vimeo/videos/route.ts. The Vimeo API base URL is https://api.vimeo.com. To fetch all videos from your account, call GET /me/videos with query parameters for fields (to select only the data you need), per_page (default 25, max 100), and sort. The response includes an array of video objects, each with id, name, description, duration, created_time, statistics (plays, likes, comments), and pictures (thumbnails at various sizes). For the embed URL, Vimeo videos use the format https://player.vimeo.com/video/{video_id}. You can extract the numeric video ID from the video's uri field (e.g., /videos/123456789). The thumbnail URL comes from the pictures.sizes array — pick the size closest to your display dimensions (640x360 is a good default). Always specify a fields parameter in your Vimeo API requests to avoid fetching unnecessary data — the full video object can be several kilobytes, but you typically only need 8-10 fields for a gallery view. This significantly improves response times.

1import { NextResponse } from 'next/server';
2
3const VIMEO_API_BASE = 'https://api.vimeo.com';
4const ACCESS_TOKEN = process.env.VIMEO_ACCESS_TOKEN;
5
6export async function GET(request: Request) {
7  if (!ACCESS_TOKEN) {
8    return NextResponse.json(
9      { error: 'Vimeo access token not configured' },
10      { status: 500 }
11    );
12  }
13
14  const { searchParams } = new URL(request.url);
15  const query = searchParams.get('query') || '';
16  const page = searchParams.get('page') || '1';
17
18  const params = new URLSearchParams({
19    fields: 'uri,name,duration,created_time,statistics,pictures',
20    per_page: '25',
21    page,
22    sort: 'date',
23    direction: 'desc',
24    ...(query && { query }),
25  });
26
27  const response = await fetch(
28    `${VIMEO_API_BASE}/me/videos?${params}`,
29    {
30      headers: {
31        Authorization: `Bearer ${ACCESS_TOKEN}`,
32        Accept: 'application/vnd.vimeo.*+json;version=3.4',
33      },
34      next: { revalidate: 300 }, // Cache for 5 minutes
35    }
36  );
37
38  if (!response.ok) {
39    const error = await response.json();
40    return NextResponse.json(
41      { error: error.error || 'Vimeo API error' },
42      { status: response.status }
43    );
44  }
45
46  const data = await response.json();
47
48  // Normalize the response for the frontend
49  const videos = data.data.map((video: any) => ({
50    id: video.uri.split('/').pop(),
51    title: video.name,
52    duration: video.duration,
53    createdAt: video.created_time,
54    plays: video.statistics?.plays || 0,
55    thumbnail: video.pictures?.sizes?.find(
56      (s: any) => s.width >= 640
57    )?.link || video.pictures?.sizes?.[0]?.link || '',
58    embedUrl: `https://player.vimeo.com/video/${video.uri.split('/').pop()}`,
59  }));
60
61  return NextResponse.json({
62    videos,
63    total: data.total,
64    page: data.page,
65    perPage: data.per_page,
66  });
67}

Your Vimeo access token must be stored as a server-side environment variable in Vercel — never hardcoded in your source code or committed to Git. Go to your Vercel Dashboard, select your project, click 'Settings' in the top navigation, then click 'Environment Variables' in the left sidebar. Create a new variable named VIMEO_ACCESS_TOKEN and paste your Personal Access Token as the value. Make sure to select all three environment scopes — Production, Preview, and Development — so your app works in all deployment contexts. Click 'Save'. To get your access token, visit developer.vimeo.com, click 'My Apps', then either create a new app or select an existing one. Under 'Authentication', click 'Generate an Access Token'. Select the scopes your app needs: 'public' and 'private' are required for fetching videos; add 'stats' if you need analytics data. Copy the generated token — Vimeo shows it only once. After adding the environment variable in Vercel, you need to redeploy your application for the change to take effect. Vercel environment variables are injected at build time and runtime — changing them in the Dashboard does not automatically update a running deployment. Go to your project's Deployments tab, click the three-dot menu on your latest deployment, and select 'Redeploy'. For local development, create a .env.local file in your project root (make sure it's in .gitignore) and add VIMEO_ACCESS_TOKEN=your_token_here. Next.js automatically loads .env.local during local development.

1# .env.local (never commit this file)
2VIMEO_ACCESS_TOKEN=your_personal_access_token_here

Now connect your V0-generated gallery component to the API route. Install the @vimeo/player npm package, which provides a JavaScript API for controlling Vimeo embeds — play, pause, seek, get duration, listen for events like 'play', 'pause', 'ended', and 'timeupdate'. Run npm install @vimeo/player in your terminal, or add it to your package.json. In your gallery component, replace the placeholder data with a useEffect hook that fetches from /api/vimeo/videos when the component mounts. Use React state to store the video list, loading state, and any search query. For the video modal, replace the plain iframe with a div ref that the Vimeo Player SDK attaches to. This gives you JavaScript control over playback — you can auto-play when the modal opens and stop playback when it closes. Use the Player constructor with options like autoplay: true, responsive: true, and dnt: true (do not track — Vimeo's privacy option). The responsive option makes the player fill its container while maintaining the 16:9 aspect ratio, which is essential for a good mobile experience. Pass the video ID as the id option to the Player constructor. When the modal closes, call player.destroy() to remove the player and stop video playback — this prevents audio from continuing after the modal is dismissed. For the search feature, debounce the search input and pass the query parameter to the API route. Add a loading skeleton state so the UI doesn't jump when video data is being fetched.

1'use client';
2import { useState, useEffect, useRef } from 'react';
3import Player from '@vimeo/player';
4
5interface VimeoVideo {
6  id: string;
7  title: string;
8  duration: number;
9  plays: number;
10  thumbnail: string;
11  embedUrl: string;
12}
13
14export function VimeoGallery() {
15  const [videos, setVideos] = useState<VimeoVideo[]>([]);
16  const [loading, setLoading] = useState(true);
17  const [selectedVideo, setSelectedVideo] = useState<VimeoVideo | null>(null);
18  const [searchQuery, setSearchQuery] = useState('');
19  const playerRef = useRef<Player | null>(null);
20  const embedRef = useRef<HTMLDivElement | null>(null);
21
22  useEffect(() => {
23    const timer = setTimeout(() => {
24      fetchVideos(searchQuery);
25    }, 300);
26    return () => clearTimeout(timer);
27  }, [searchQuery]);
28
29  async function fetchVideos(query: string) {
30    setLoading(true);
31    try {
32      const params = query ? `?query=${encodeURIComponent(query)}` : '';
33      const res = await fetch(`/api/vimeo/videos${params}`);
34      const data = await res.json();
35      setVideos(data.videos || []);
36    } catch (err) {
37      console.error('Failed to fetch Vimeo videos:', err);
38    } finally {
39      setLoading(false);
40    }
41  }
42
43  useEffect(() => {
44    if (selectedVideo && embedRef.current) {
45      playerRef.current = new Player(embedRef.current, {
46        id: parseInt(selectedVideo.id),
47        autoplay: true,
48        responsive: true,
49        dnt: true,
50      });
51    }
52    return () => {
53      playerRef.current?.destroy();
54      playerRef.current = null;
55    };
56  }, [selectedVideo]);
57
58  function formatDuration(seconds: number) {
59    const m = Math.floor(seconds / 60);
60    const s = seconds % 60;
61    return `${m}:${s.toString().padStart(2, '0')}`;
62  }
63
64  return (
65    <div className="max-w-6xl mx-auto px-4 py-8">
66      <input
67        type="text"
68        placeholder="Search videos..."
69        value={searchQuery}
70        onChange={(e) => setSearchQuery(e.target.value)}
71        className="w-full mb-6 px-4 py-2 border rounded-lg"
72      />
73      {loading ? (
74        <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6">
75          {[...Array(6)].map((_, i) => (
76            <div key={i} className="animate-pulse bg-gray-200 rounded-lg h-48" />
77          ))}
78        </div>
79      ) : (
80        <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6">
81          {videos.map((video) => (
82            <div
83              key={video.id}
84              className="cursor-pointer rounded-lg overflow-hidden shadow hover:shadow-lg transition"
85              onClick={() => setSelectedVideo(video)}
86            >
87              <img src={video.thumbnail} alt={video.title} className="w-full aspect-video object-cover" />
88              <div className="p-3">
89                <h3 className="font-semibold truncate">{video.title}</h3>
90                <p className="text-sm text-gray-500">{formatDuration(video.duration)} · {video.plays.toLocaleString()} plays</p>
91              </div>
92            </div>
93          ))}
94        </div>
95      )}
96      {selectedVideo && (
97        <div className="fixed inset-0 bg-black/80 flex items-center justify-center z-50 p-4">
98          <div className="w-full max-w-3xl bg-black rounded-lg overflow-hidden">
99            <div ref={embedRef} className="aspect-video" />
100            <button
101              onClick={() => setSelectedVideo(null)}
102              className="mt-2 px-4 py-2 text-white hover:text-gray-300"
103            >Close</button>
104          </div>
105        </div>
106      )}
107    </div>
108  );
109}

With the API route and component connected, deploy your application to Vercel to test the full integration in a production environment. If you haven't already connected your V0 project to GitHub, go to V0's Git panel, click 'Connect to GitHub', authorize the GitHub integration, and push your code. Vercel automatically detects new commits and triggers deployments. After deploying, visit your production URL and test the video gallery. Click a video card to verify the Vimeo Player loads and plays correctly. Test the search functionality to confirm the API route receives the query parameter. Check your browser's Network tab to ensure no Vimeo access token appears in client-side requests — all API calls should go to /api/vimeo/videos (your internal API route), not directly to api.vimeo.com. For debugging, check Vercel's function logs in the Dashboard under your deployment's Functions tab. If the API route returns an error, the logs will show the full error response from the Vimeo API, which makes diagnosing authentication and permission issues much easier than inspecting the browser console alone. Vercel Preview Deployments are useful here — every pull request gets a unique preview URL with its own deployment, and since you set the environment variable for all scopes (Production, Preview, Development), the Vimeo integration works in preview deployments too. Share preview URLs with clients or teammates to get feedback on video layout before merging to production.