Convex ファイルストレージ

Convex アプリケーションでファイルのアップロード、ストレージ、配信、管理を適切なパターンで処理します。画像、ドキュメント、生成されたファイルに対応しています。

ドキュメントソース

実装する前に仮定をせず、最新のドキュメントを確認してください:

• Primary: https://docs.convex.dev/file-storage
• Upload Files: https://docs.convex.dev/file-storage/upload-files
• Serve Files: https://docs.convex.dev/file-storage/serve-files
• 詳細情報: https://docs.convex.dev/llms.txt

説明

ファイルストレージの概要

Convex には以下の機能を備えた組み込みファイルストレージがあります:

• ファイル提供用の自動 URL 生成
• あらゆるファイルタイプのサポート (画像、PDF、動画など)
• _storage システムテーブルを通じたファイルメタデータ
• ミューテーションとアクションとの統合

アップロード URL の生成

// convex/files.ts
import { mutation } from "./_generated/server";
import { v } from "convex/values";

export const generateUploadUrl = mutation({
  args: {},
  returns: v.string(),
  handler: async (ctx) => {
    return await ctx.storage.generateUploadUrl();
  },
});

クライアント側のアップロード

// React component
import { useMutation } from "convex/react";
import { api } from "../convex/_generated/api";
import { useState } from "react";

function FileUploader() {
  const generateUploadUrl = useMutation(api.files.generateUploadUrl);
  const saveFile = useMutation(api.files.saveFile);
  const [uploading, setUploading] = useState(false);

  const handleUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    setUploading(true);
    try {
      // Step 1: アップロード URL を取得
      const uploadUrl = await generateUploadUrl();

      // Step 2: ストレージにファイルをアップロード
      const result = await fetch(uploadUrl, {
        method: "POST",
        headers: { "Content-Type": file.type },
        body: file,
      });

      const { storageId } = await result.json();

      // Step 3: ファイル参照をデータベースに保存
      await saveFile({
        storageId,
        fileName: file.name,
        fileType: file.type,
        fileSize: file.size,
      });
    } finally {
      setUploading(false);
    }
  };

  return (
    <div>
      <input
        type="file"
        onChange={handleUpload}
        disabled={uploading}
      />
      {uploading && <p>Uploading...</p>}
    </div>
  );
}

ファイル参照の保存

// convex/files.ts
import { mutation, query } from "./_generated/server";
import { v } from "convex/values";

export const saveFile = mutation({
  args: {
    storageId: v.id("_storage"),
    fileName: v.string(),
    fileType: v.string(),
    fileSize: v.number(),
  },
  returns: v.id("files"),
  handler: async (ctx, args) => {
    return await ctx.db.insert("files", {
      storageId: args.storageId,
      fileName: args.fileName,
      fileType: args.fileType,
      fileSize: args.fileSize,
      uploadedAt: Date.now(),
    });
  },
});

URL を経由したファイルの配信

// convex/files.ts
export const getFileUrl = query({
  args: { storageId: v.id("_storage") },
  returns: v.union(v.string(), v.null()),
  handler: async (ctx, args) => {
    return await ctx.storage.getUrl(args.storageId);
  },
});

// URL 付きでファイルを取得
export const getFile = query({
  args: { fileId: v.id("files") },
  returns: v.union(
    v.object({
      _id: v.id("files"),
      fileName: v.string(),
      fileType: v.string(),
      fileSize: v.number(),
      url: v.union(v.string(), v.null()),
    }),
    v.null()
  ),
  handler: async (ctx, args) => {
    const file = await ctx.db.get(args.fileId);
    if (!file) return null;

    const url = await ctx.storage.getUrl(file.storageId);
    
    return {
      _id: file._id,
      fileName: file.fileName,
      fileType: file.fileType,
      fileSize: file.fileSize,
      url,
    };
  },
});

React でファイルを表示

import { useQuery } from "convex/react";
import { api } from "../convex/_generated/api";

function FileDisplay({ fileId }: { fileId: Id<"files"> }) {
  const file = useQuery(api.files.getFile, { fileId });

  if (!file) return <div>Loading...</div>;
  if (!file.url) return <div>File not found</div>;

  // ファイルタイプに応じて処理
  if (file.fileType.startsWith("image/")) {
    return <img src={file.url} alt={file.fileName} />;
  }

  if (file.fileType === "application/pdf") {
    return (
      <iframe
        src={file.url}
        title={file.fileName}
        width="100%"
        height="600px"
      />
    );
  }

  return (
    <a href={file.url} download={file.fileName}>
      Download {file.fileName}
    </a>
  );
}

アクションから生成されたファイルの保存

// convex/generate.ts
"use node";

import { action } from "./_generated/server";
import { v } from "convex/values";
import { api } from "./_generated/api";

export const generatePDF = action({
  args: { content: v.string() },
  returns: v.id("_storage"),
  handler: async (ctx, args) => {
    // PDF を生成 (ライブラリを使用した例)
    const pdfBuffer = await generatePDFFromContent(args.content);

    // Blob に変換
    const blob = new Blob([pdfBuffer], { type: "application/pdf" });

    // Convex に保存
    const storageId = await ctx.storage.store(blob);

    return storageId;
  },
});

// 画像を生成して保存
export const generateImage = action({
  args: { prompt: v.string() },
  returns: v.id("_storage"),
  handler: async (ctx, args) => {
    // 外部 API を呼び出して画像を生成
    const response = await fetch("https://api.example.com/generate", {
      method: "POST",
      body: JSON.stringify({ prompt: args.prompt }),
    });

    const imageBuffer = await response.arrayBuffer();
    const blob = new Blob([imageBuffer], { type: "image/png" });

    return await ctx.storage.store(blob);
  },
});

ファイルメタデータへのアクセス

// convex/files.ts
import { query } from "./_generated/server";
import { v } from "convex/values";
import { Id } from "./_generated/dataModel";

type FileMetadata = {
  _id: Id<"_storage">;
  _creationTime: number;
  contentType?: string;
  sha256: string;
  size: number;
};

export const getFileMetadata = query({
  args: { storageId: v.id("_storage") },
  returns: v.union(
    v.object({
      _id: v.id("_storage"),
      _creationTime: v.number(),
      contentType: v.optional(v.string()),
      sha256: v.string(),
      size: v.number(),
    }),
    v.null()
  ),
  handler: async (ctx, args) => {
    const metadata = await ctx.db.system.get(args.storageId);
    return metadata as FileMetadata | null;
  },
});

ファイルの削除

// convex/files.ts
import { mutation } from "./_generated/server";
import { v } from "convex/values";

export const deleteFile = mutation({
  args: { fileId: v.id("files") },
  returns: v.null(),
  handler: async (ctx, args) => {
    const file = await ctx.db.get(args.fileId);
    if (!file) return null;

    // ストレージから削除
    await ctx.storage.delete(file.storageId);

    // データベースレコードを削除
    await ctx.db.delete(args.fileId);

    return null;
  },
});

プレビュー付き画像アップロード

import { useMutation } from "convex/react";
import { api } from "../convex/_generated/api";
import { useState, useRef } from "react";

function ImageUploader({ onUpload }: { onUpload: (id: Id<"files">) => void }) {
  const generateUploadUrl = useMutation(api.files.generateUploadUrl);
  const saveFile = useMutation(api.files.saveFile);
  const [preview, setPreview] = useState<string | null>(null);
  const [uploading, setUploading] = useState(false);
  const inputRef = useRef<HTMLInputElement>(null);

  const handleFileSelect = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    // ファイルタイプを検証
    if (!file.type.startsWith("image/")) {
      alert("Please select an image file");
      return;
    }

    // ファイルサイズを検証 (最大 10MB)
    if (file.size > 10 * 1024 * 1024) {
      alert("File size must be less than 10MB");
      return;
    }

    // プレビューを表示
    const reader = new FileReader();
    reader.onload = (e) => setPreview(e.target?.result as string);
    reader.readAsDataURL(file);

    // アップロード
    setUploading(true);
    try {
      const uploadUrl = await generateUploadUrl();
      const result = await fetch(uploadUrl, {
        method: "POST",
        headers: { "Content-Type": file.type },
        body: file,
      });

      const { storageId } = await result.json();
      const fileId = await saveFile({
        storageId,
        fileName: file.name,
        fileType: file.type,
        fileSize: file.size,
      });

      onUpload(fileId);
    } finally {
      setUploading(false);
    }
  };

  return (
    <div>
      <input
        ref={inputRef}
        type="file"
        accept="image/*"
        onChange={handleFileSelect}
        style={{ display: "none" }}
      />
      
      <button
        onClick={() => inputRef.current?.click()}
        disabled={uploading}
      >
        {uploading ? "Uploading..." : "Select Image"}
      </button>

      {preview && (
        <img
          src={preview}
          alt="Preview"
          style={{ maxWidth: 200, marginTop: 10 }}
        />
      )}
    </div>
  );
}

例

ファイルストレージ用スキーマ

// convex/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  files: defineTable({
    storageId: v.id("_storage"),
    fileName: v.string(),
    fileType: v.string(),
    fileSize: v.number(),
    uploadedBy: v.id("users"),
    uploadedAt: v.number(),
  })
    .index("by_user", ["uploadedBy"])
    .index("by_type", ["fileType"]),

  // ユーザーアバター
  users: defineTable({
    name: v.string(),
    email: v.string(),
    avatarStorageId: v.optional(v.id("_storage")),
  }),

  // 画像付き投稿
  posts: defineTable({
    authorId: v.id("users"),
    content: v.string(),
    imageStorageIds: v.array(v.id("_storage")),
    createdAt: v.number(),
  }).index("by_author", ["authorId"]),
});

ベストプラクティス

• 明確に指示されない限り npx convex deploy を実行しない
• 明確に指示されない限り git コマンドを実行しない
• アップロード前にクライアントでファイルタイプとサイズを検証する
• ファイルメタデータ (名前、タイプ、サイズ) を独自のテーブルに保存する
• _storage システムテーブルは Convex メタデータのみに使用する
• データベース参照を削除する際にストレージファイルも削除する
• アップロード時に適切な Content-Type ヘッダーを使用する
• 大きい画像の場合は画像最適化を検討する

よくある落とし穴

1. Content-Type ヘッダーを設定していない - ファイルが正しく配信されない可能性があります
2. ストレージの削除を忘れる - 孤立したファイルがストレージを無駄にします
3. ファイルタイプを検証していない - 悪意のあるアップロードに対するセキュリティリスク
4. 大きなファイルアップロードで進捗状況がない - ユーザーエクスペリエンスが悪い
5. 非推奨の getMetadata を使用する - 代わりに ctx.db.system.get を使用してください

リファレンス

• Convex ドキュメント: https://docs.convex.dev/
• Convex LLMs.txt: https://docs.convex.dev/llms.txt
• ファイルストレージ: https://docs.convex.dev/file-storage
• ファイルアップロード: https://docs.convex.dev/file-storage/upload-files
• ファイル配信: https://docs.convex.dev/file-storage/serve-files