Vercelの設定ファイルがTypeScriptでも書けるようになった
はじめに
昨年2025年12月19日、Vercelから新しい設定方法「vercel.ts」がリリースされました。
今回個人的に調べている中で得た情報をまとめます。
これまでVercelのプロジェクト設定はvercel.jsonというJSONファイルで行っていましたが、新たにTypeScriptベースの設定ファイルvercel.tsがサポートされました。型安全性、動的な設定生成、そしてより良い開発者体験をプロジェクト設定にもたらします。
本記事では、vercel.tsの概要と基本的な使い方を紹介します。
vercel.tsとは
vercel.tsは、Vercelのプロジェクト設定をTypeScriptベースで記述できる新しい設定ファイルです。
従来のvercel.jsonでは表現できなかった以下のことが可能になります。
- 型安全性:
@vercel/configパッケージによる完全な型サポートとIDEの補完機能 - 動的な設定生成: ビルド時に環境変数へのアクセス、条件分岐、共有ロジックが利用可能
- ヘルパー関数:
routes.rewrite()、routes.redirect()などの便利な関数
すべてのプロジェクトでvercel.ts（または.js、.mjs、.cjs、.mts）を使用できます。
セットアップ
1. @vercel/configパッケージのインストール
型やヘルパーが含まれています。
npm install @vercel/config
2. vercel.tsファイルの作成
プロジェクトルートにvercel.tsを作成し、configをエクスポートします。
import type { VercelConfig } from '@vercel/config/v1';
export const config: VercelConfig = {
// 設定をここに記述
};
注意点: vercel.tsとvercel.jsonを両方持つことはできません。どちらか一方のみを使用してください。
基本的な使い方
シンプルな設定例
import type { VercelConfig } from '@vercel/config/v1';
export const config: VercelConfig = {
buildCommand: 'npm run build',
framework: 'nextjs',
cleanUrls: true,
trailingSlash: false,
};
vercel.jsonと同じプロパティ名を使用できます。
ヘルパー関数を使った設定例
@vercel/configパッケージが提供するヘルパー関数を使うと、より読みやすい設定が書けます。
import { routes, deploymentEnv, type VercelConfig } from '@vercel/config/v1';
export const config: VercelConfig = {
framework: 'nextjs',
// Cronジョブの設定
crons: [
{ path: '/api/cleanup', schedule: '0 0 * * *' },
{ path: '/api/sync-users', schedule: '*/15 * * * *' },
],
// リライトの設定
rewrites: [
routes.rewrite('/(.*)', 'https://external-api.com/$1', {
requestHeaders: {
'proxy-header': deploymentEnv('PROXY_HEADER'),
},
}),
],
// リダイレクトの設定
redirects: [
routes.redirect('/old-docs', '/docs', { permanent: true }),
],
// ヘッダーの設定
headers: [
// キャッシュ制御用のヘルパー
routes.cacheControl('/static/(.*)', {
public: true,
maxAge: '1 week',
immutable: true,
}),
// 汎用ヘッダー設定
routes.header('/(.*)', [
{ key: 'X-Content-Type-Options', value: 'nosniff' },
{ key: 'X-Frame-Options', value: 'DENY' },
]),
],
};
型安全なパスパラメータ
リライトやリダイレクトでパスパラメータを使う場合、コールバック関数で型安全にアクセスできます。
import { routes, deploymentEnv, type VercelConfig } from '@vercel/config/v1';
export const config: VercelConfig = {
rewrites: [
// パスパラメータを型安全に利用
routes.rewrite(
'/users/:userId/posts/:postId',
'https://api.example.com/users/$1/posts/$2',
({ userId, postId }) => ({
requestHeaders: {
'x-user-id': userId,
'x-post-id': postId,
authorization: `Bearer ${deploymentEnv('API_KEY')}`,
},
})
),
],
};
環境変数の利用
deploymentEnv()を使用するとVercelの環境変数を参照できます。
import { routes, deploymentEnv } from '@vercel/config/v1';
export const config: VercelConfig = {
rewrites: [
routes.rewrite('/(.*)', 'https://api.example.com/$1', {
requestHeaders: {
authorization: `Bearer ${deploymentEnv('API_TOKEN')}`,
},
}),
],
};
CLIコマンド
@vercel/configパッケージはCLIコマンドも提供しています。
# vercel.tsをJSONにコンパイル（標準出力）
npx @vercel/config compile
# 設定のエラーチェックとサマリー表示
npx @vercel/config validate
# vercel.jsonをローカルに生成（開発用）
npx @vercel/config generate
補足: Vercel CLIはvercel.tsを自動的にコンパイルするため、通常は手動でコンパイルする必要はありません。
vercel.jsonからの移行
既存のvercel.jsonから移行する場合、内容をそのままconfigエクスポートにコピーできます。
移行前（vercel.json）:
{
"buildCommand": "pnpm run generate-config",
"outputDirectory": ".next",
"headers": [
{
"source": "/(.*)\\.(js|css|jpg|jpeg|gif|png|svg|txt|ttf|woff2|webmanifest)",
"headers": [
{
"key": "Cache-Control",
"value": "public, max-age=2592000, s-maxage=2592000"
}
]
}
]
}
移行後（vercel.ts）:
import { type VercelConfig, routes } from '@vercel/config/v1';
export const config: VercelConfig = {
buildCommand: 'pnpm run generate-config',
outputDirectory: '.next',
headers: [
routes.cacheControl('/(.*)\.(js|css|jpg|jpeg|gif|png|svg|txt|ttf|woff2|webmanifest)', {
public: true,
maxAge: '4 week',
sMaxAge: '4 week'
})
]
};
ヘルパー関数を使うことで、より読みやすく型安全な設定に書き換えられます。
Playgroundで試す
Vercelは公式のPlaygroundを提供しており、ブラウザ上でvercel.tsを試すことができます。
左側にvercel.jsonを貼り付けると、右側にTypeScript版が生成されます。既存プロジェクトの移行時に便利です。
主な設定プロパティ
vercel.tsで使用できる主なプロパティを紹介します。すべてvercel.jsonと同じプロパティ名です。
| プロパティ | 説明 |
|---|---|
buildCommand |
ビルドコマンドを上書き |
installCommand |
インストールコマンドを上書き |
outputDirectory |
出力ディレクトリを指定 |
framework |
フレームワークプリセットを指定 |
regions |
Vercel Functionsを実行するリージョン |
crons |
Cronジョブの設定 |
rewrites |
リライトルールの設定 |
redirects |
リダイレクトルールの設定 |
headers |
レスポンスヘッダーの設定 |
cleanUrls |
URLから拡張子を削除 |
trailingSlash |
末尾スラッシュの制御 |
詳細は公式ドキュメントを参照してください。
まとめ
vercel.tsにより、Vercelのプロジェクト設定がTypeScriptで書けるようになりました。
- 型安全: IDEの補完と型チェック
- 動的な設定: 環境変数や条件分岐を使った柔軟な設定
- ヘルパー関数: 読みやすく書きやすいAPI
既存のvercel.jsonからの移行も簡単なので、TypeScriptプロジェクトでは積極的に活用していきたいですね。
