Strapi Client

Strapi Client ライブラリはバックエンドとのやり取りを簡素化し、コンテンツの取得・作成・更新・削除が行えます。このガイドではセットアップ、認証の設定、主な機能の使い方を説明します。

はじめに

Prerequisites

Strapi プロジェクトが作成済みで動いていること。まだの場合はクイックスタートに従って作成してください。
Strapi インスタンスの Content API の URL を把握していること（例: http://localhost:1337/api）。

インストール

Strapi Client をプロジェクトで使うには、好みのパッケージマネージャーで依存関係に追加します。

Yarn
NPM
pnpm

yarn add @strapi/client

npm install @strapi/client

pnpm add @strapi/client

基本的な設定

バックエンドと通信するには、Strapi Client を初期化し、API のベース URL を設定します。

JavaScript
TypeScript
ブラウザ（UMD）

JavaScript では strapi 関数をインポートしてクライアントインスタンスを作ります。

import { strapi } from '@strapi/client';

const client = strapi({ baseURL: 'http://localhost:1337/api' });

TypeScript では strapi 関数をインポートし、Strapi API のベース URL を指定してクライアントインスタンスを作ります。

import { strapi } from '@strapi/client';

const client = strapi({ baseURL: 'http://localhost:1337/api' });

ブラウザでは <script> タグで Strapi Client を読み込めます。

./src/api/[apiName]/routes/[routerName].ts (例: './src/api/restaurant/routes/restaurant.ts')
<script src="https://cdn.jsdelivr.net/npm/@strapi/client"></script>

<script>
  const client = strapi.strapi({ baseURL: 'http://localhost:1337/api' });
</script>

baseURL にはプロトコル（http または https）を含める必要があります。無効な URL の場合は StrapiInitializationError がスローされます。

認証

Strapi Client は複数の認証方式に対応し、バックエンドの保護されたリソースにアクセスできます。

Strapi で API トークンを使っている場合は、次のように設定します。

const client = strapi({
  baseURL: 'http://localhost:1337/api',
  auth: 'your-api-token-here',
});

リクエストに必要な認証情報が自動で付きます。トークンが無効または欠落している場合、初期化時に StrapiValidationError がスローされます。

API リファレンス

Strapi Client がバックエンドとやり取りするための主なプロパティとメソッドは次のとおりです。

パラメータ	説明
`baseURL`	Strapi バックエンドの API ベース URL。
`fetch()`	ネイティブの fetch API に近い、汎用 API リクエスト用のメソッド。
`collection()`	コレクションタイプのリソースを扱います（ブログ記事や商品など）。
`single()`	シングルタイプのリソースを扱います（ホームページ設定や全体設定など）。
`files()`	Strapi メディアライブラリへのファイルのアップロード・取得・管理を行います。

汎用の fetch

Strapi Client から、初期化時に指定したベース URL を基準にした直接リクエスト用に JavaScript の fetch に相当する手段が使えます。

const result = await client.fetch('articles', { method: 'GET' });

コレクションタイプの操作

Strapi のコレクションタイプは複数エントリを持つエンティティです（多数の投稿があるブログなど）。collection() で操作し、次のメソッドが使えます。

パラメータ	説明
`find(queryParams?)`	フィルター・ソート・ページネーションなどの任意パラメータ付きで複数ドキュメントを取得します。
`findOne(documentID, queryParams?)`	一意の ID で 1 件のドキュメントを取得します。
`create(data, queryParams?)`	コレクションに新しいドキュメントを作成します。
`update(documentID, data, queryParams?)`	既存のドキュメントを更新します。
`delete(documentID, queryParams?)`	既存のドキュメントを削除します。

使用例:

JavaScript

const articles = client.collection('articles');

// タイトルでソートした英語の記事をすべて取得
const allArticles = await articles.find({
  locale: 'en',
  sort: 'title',
});

// 1 件の記事を取得
const singleArticle = await articles.findOne('article-document-id');

// 新しい記事を作成
const newArticle = await articles.create({ title: 'New Article', content: '...' });

// 既存の記事を更新
const updatedArticle = await articles.update('article-document-id', { title: 'Updated Title' });

// 記事を削除
await articles.delete('article-id');

シングルタイプの操作

シングルタイプはアプリ内で 1 つだけ存在するコンテンツ（ホームページ設定やサイト全体の設定など）です。single() で操作し、次のメソッドが使えます。

パラメータ	説明
`find(queryParams?)`	ドキュメントを取得します。
`update(documentID, data, queryParams?)`	ドキュメントを更新します。
`delete(queryParams?)`	ドキュメントを削除します。

使用例:

const homepage = client.single('homepage');

// 既定のホームページコンテンツを取得
const defaultHomepage = await homepage.find();

// ホームページのスペイン語版を取得
const spanishHomepage = await homepage.find({ locale: 'es' });

// ホームページの下書きを更新
const updatedHomepage = await homepage.update(
  { title: 'Updated Homepage Title' },
  { status: 'draft' }
);

// ホームページのコンテンツを削除
await homepage.delete();

ファイルの操作

Strapi Client はメディアライブラリに files 経由でアクセスします。REST API を直接使わずにファイルのメタデータを取得・管理できます。

ファイル操作用のメソッドは次のとおりです。表のメソッド名をクリックすると、詳細と例のある見出しへ移動します。

メソッド	説明
`find(params?)`	任意のクエリパラメータに基づき、ファイルメタデータの一覧を取得します
`findOne(fileId)`	ID で 1 件のファイルメタデータを取得します
`update(fileId, fileInfo)`	既存ファイルのメタデータを更新します
`upload(file, options)`	ファイル（Blob または Buffer）をアップロードします。メタデータ用の任意の `options` を付けられます
`delete(fileId)`	ID でファイルを削除します

`find`

strapi.client.files.find() は、任意のクエリパラメータに基づきファイルメタデータの一覧を返します。

次のように使います。

// クライアントを初期化
const client = strapi({
  baseURL: 'http://localhost:1337/api',
  auth: 'your-api-token',
});

// すべてのファイルメタデータを取得
const allFiles = await client.files.find();
console.log(allFiles);

// フィルターとソート付きでファイルメタデータを取得
const imageFiles = await client.files.find({
  filters: {
    mime: { $contains: 'image' }, // 画像のみ
    name: { $contains: 'avatar' }, // 名前に avatar を含むもののみ
  },
  sort: ['name:asc'], // 名前の昇順
});

`findOne`

strapi.client.files.findOne() は、ID で 1 件のファイルメタデータを返します。

次のように使います。

// クライアントを初期化
const client = strapi({
  baseURL: 'http://localhost:1337/api',
  auth: 'your-api-token',
});

// ID でファイルメタデータを取得
const file = await client.files.findOne(1);
console.log(file.name);
console.log(file.url); 
console.log(file.mime); // ファイルの MIME タイプ

`update`

strapi.client.files.update() は既存ファイルのメタデータを更新します。引数は fileId と、名前・代替テキスト・キャプションなどを含むオプションオブジェクトです。

次のように使います。

// クライアントを初期化
const client = strapi({
  baseURL: 'http://localhost:1337/api',
  auth: 'your-api-token',
});

// ファイルメタデータを更新
const updatedFile = await client.files.update(1, {
  name: 'New file name',
  alternativeText: 'Descriptive alt text for accessibility',
  caption: 'A caption for the file',
});

`upload` NewThis content is new.

Strapi Client は FilesManager 経由でメディアをアップロードでき、strapi.client.files.upload() から利用します。画像・動画・文書などをバックエンドに送れます。

ブラウザまたは Node.js では Blob、Node.js では Buffer としてアップロードできます。alternativeText や caption などのメタデータも付けられます。

メソッドシグネチャ

async upload(file: Blob, options?: BlobUploadOptions): Promise<MediaUploadResponse>
async upload(file: Buffer, options: BufferUploadOptions): Promise<MediaUploadResponse>

Blob のとき options は任意で、fileInfo でメタデータを渡せます。
Buffer のとき options には filename と mimetype が必須で、fileInfo は任意です。

レスポンスはファイルオブジェクトの配列で、id、name、url、size、mime などが含まれます（型定義の出典）。

ブラウザでファイルをアップロード
Node.js でファイルをアップロード

ブラウザからは次のようにアップロードできます。

const client = strapi({ baseURL: 'http://localhost:1337/api' });

const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

try {
  const result = await client.files.upload(file, {
    fileInfo: {
      alternativeText: 'A user uploaded image',
      caption: 'Uploaded via browser',
    },
  });
  console.log('Upload successful:', result);
} catch (error) {
  console.error('Upload failed:', error);
}

Node.js では Blob または Buffer のどちらでもアップロードできます。

Blob でアップロード
Buffer でアップロード

import { readFile } from 'fs/promises';

const client = strapi({ baseURL: 'http://localhost:1337/api' });

const filePath = './image.png';
const mimeType = 'image/png';
const fileContentBuffer = await readFile(filePath);
const fileBlob = new Blob([fileContentBuffer], { type: mimeType });

try {
  const result = await client.files.upload(fileBlob, {
    fileInfo: {
      name: 'Image uploaded as Blob',
      alternativeText: 'Uploaded from Node.js Blob',
      caption: 'Example upload',
    },
  });
  console.log('Blob upload successful:', result);
} catch (error) {
  console.error('Blob upload failed:', error);
}

import { readFile } from 'fs/promises';

const client = strapi({ baseURL: 'http://localhost:1337/api' });

const filePath = './image.png';
const fileContentBuffer = await readFile(filePath);

try {
  const result = await client.files.upload(fileContentBuffer, {
    filename: 'image.png',
    mimetype: 'image/png',
    fileInfo: {
      name: 'Image uploaded as Buffer',
      alternativeText: 'Uploaded from Node.js Buffer',
      caption: 'Example upload',
    },
  });
  console.log('Buffer upload successful:', result);
} catch (error) {
  console.error('Buffer upload failed:', error);
}

レスポンスの形

strapi.client.files.upload() は、次のようなフィールドを持つファイルオブジェクトの配列を返します。

{
  "id": 1,
  "name": "image.png",
  "alternativeText": "Uploaded from Node.js Buffer",
  "caption": "Example upload",
  "mime": "image/png",
  "url": "/uploads/image.png",
  "size": 12345,
  "createdAt": "2025-07-23T12:34:56.789Z",
  "updatedAt": "2025-07-23T12:34:56.789Z"
}

レスポンスの追加フィールド

アップロードのレスポンスには、ここに示した以外のフィールドも含まれます。利用可能なすべてのフィールドはクライアントのソースコード内の FileResponse を参照してください。

`delete`

strapi.client.files.delete() は ID を指定してファイルを削除します。

次のように使います。

// クライアントを初期化
const client = strapi({
  baseURL: 'http://localhost:1337/api',
  auth: 'your-api-token',
});

// ID でファイルを削除
const deletedFile = await client.files.delete(1);
console.log('File deleted successfully');
console.log('Deleted file ID:', deletedFile.id);
console.log('Deleted file name:', deletedFile.name);

よくあるエラー

Strapi Client 経由のクエリで次のエラーが発生することがあります。

エラー	説明
権限エラー	認証されたユーザーにファイルのアップロードや管理の権限がない場合、`FileForbiddenError` がスローされます。
HTTP エラー	サーバーに到達できない、認証に失敗した、ネットワークに問題がある場合、`HTTPError` がスローされます。
パラメータ不足	`Buffer` をアップロードするとき、`options` に `filename` と `mimetype` の両方が必要です。どちらかが欠けるとエラーになります。

追加情報

Strapi Client の詳細はパッケージの README を参照してください。

はじめに​

インストール​

基本的な設定​

認証​

API リファレンス​

汎用の fetch​

コレクションタイプの操作​

シングルタイプの操作​

ファイルの操作​

find​

findOne​

update​

upload NewThis content is new.​

メソッドシグネチャ​

レスポンスの形​

delete​

よくあるエラー​

はじめに

インストール

基本的な設定

認証

API リファレンス

汎用の fetch

コレクションタイプの操作

シングルタイプの操作

ファイルの操作

`find`

`findOne`

`update`

`upload` NewThis content is new.

メソッドシグネチャ

レスポンスの形

`delete`

よくあるエラー