tRPC End-to-End Type Safe APIs · Lekcja

Przesyłanie plików z tRPC

Zintegrują Państwo funkcję przesyłania plików z mutacjami tRPC, korzystając z multipart/form-data i odpowiednich parserów.

Lekcja 3 z 411 kroki

Przesyłanie plików z tRPC to bezpłatna lekcja tRPC End-to-End Type Safe APIs na CoddyKit. To lekcja 3 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej tRPC End-to-End Type Safe APIs, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs tRPC End-to-End Type Safe APIs zawiera 4 lekcji w sumie.

Części tej lekcji nie zostały jeszcze przetłumaczone i są wyświetlane po angielsku.

Intro to File Uploads

Welcome to handling file uploads with tRPC! Unlike simple JSON data, files (like images or documents) require a special approach because they are often binary data.

tRPC itself focuses on type-safe API definitions. It doesn't natively handle the low-level parsing of file uploads. Instead, it integrates seamlessly with the underlying HTTP server framework, like Express or Next.js, to manage this.

Understanding multipart/form-data

When you upload a file via a web form, the data is typically sent using the multipart/form-data encoding type. This is different from application/json, which is common for most tRPC requests.

multipart/form-data: Allows sending both text fields and binary files in a single request.
application/json: Primarily for structured text data, not ideal for large binary files.

Your server needs a special 'parser' to correctly interpret multipart/form-data requests.

Server-side Setup: Express & Parsers

To integrate file uploads with tRPC, we'll use an Express server as our backend. Express is a popular Node.js framework that can easily host tRPC.

For parsing multipart/form-data, we'll use a middleware like express-fileupload. This middleware will process the incoming request and make the uploaded files accessible on the req object.

Basic Express Server with File Middleware

First, let's set up a basic Express server and integrate the express-fileupload middleware. This makes files available on the req object for later use.

Run npm install express express-fileupload in your project.

Try running this example:

const express = require('express');
const fileUpload = require('express-fileupload');
const app = express();
const port = 3000;

// Enable file upload middleware
app.use(fileUpload());

app.get('/', (req, res) => {
  res.send('Express server running!');
});

// Simple endpoint to show file access
app.post('/upload-test', (req, res) => {
  if (!req.files || Object.keys(req.files).length === 0) {
    return res.status(400).send('No files uploaded.');
  }
  
  // 'myFile' refers to the name attribute in the HTML input
  let uploadedFile = req.files.myFile;
  
  console.log('File received:', uploadedFile.name);
  res.send(`File '${uploadedFile.name}' received.`);
});

app.listen(port, () => {
  console.log(`Server on http://localhost:${port}`);
});

Integrating tRPC into the Server

Now, let's add tRPC on top of our Express server. It's crucial that the express-fileupload middleware runs before the tRPC middleware. This ensures that req.files is populated before tRPC's createContext function is called.

Run npm install @trpc/server @trpc/express zod.

import express from 'express';
import fileUpload from 'express-fileupload';
import * as trpcExpress from '@trpc/express';
import { initTRPC } from '@trpc/server';

// Initialize tRPC (we'll define context and router later)
const t = initTRPC.context<any>().create();
const appRouter = t.router({}); // Empty router for now

// tRPC context function
function createContext({ req, res }: { req: express.Request, res: express.Response }) {
  return { req, res, uploadedFiles: req.files }; // Files are here!
}

const app = express();
const port = 3000;

// 1. Enable file upload middleware FIRST
app.use(fileUpload());

// 2. Add tRPC middleware (after fileUpload)
app.use(
  '/trpc',
  trpcExpress.createExpressMiddleware({
    router: appRouter,
    createContext,
  })
);

app.get('/', (req, res) => {
  res.send('tRPC file upload server running!');
});

app.listen(port, () => {
  console.log(`Server on http://localhost:${port}`);
});

Defining tRPC Context with File Access

As shown in the previous example, the express-fileupload middleware adds a files property to the express.Request object. By returning req.files in our createContext function, we make the uploaded files easily accessible within any tRPC procedure.

We've named this property uploadedFiles in our context for clarity.

import express from 'express';
import type { UploadedFile } from 'express-fileupload';

// Extend Express Request type (in a real project, this would be in a types file)
declare global {
  namespace Express {
    interface Request {
      files?: { [key: string]: UploadedFile | UploadedFile[] };
    }
  }
}

export function createContext({
  req,
  res,
}: { req: express.Request; res: express.Response }) {
  return {
    req,
    res,
    // This makes the files available in `ctx.uploadedFiles`
    uploadedFiles: req.files,
  };
}

Building the File Upload Mutation

Now we can define a tRPC mutation that uses the uploadedFiles from our context. We'll use Zod for basic input validation (e.g., a description for the file).

Access ctx.uploadedFiles.
Retrieve the specific file by its field name (e.g., 'myFile').
Use the file's mv() method to save it to disk.

import { initTRPC } from '@trpc/server';
import { z } from 'zod';
import type { UploadedFile } from 'express-fileupload';

// Assuming 't' is initialized with context containing 'uploadedFiles'
const t = initTRPC.context<any>().create(); // Replace 'any' with your actual context type

export const appRouter = t.router({
  uploadFile: t.procedure
    .input(z.object({
      description: z.string().optional(),
    }))
    .mutation(async ({ ctx, input }) => {
      const { uploadedFiles } = ctx;

      if (!uploadedFiles || Object.keys(uploadedFiles).length === 0) {
        throw new Error('No files found in request.');
      }

      // Access the file by the name given in FormData (e.g., 'myFile')
      const file = uploadedFiles.myFile as UploadedFile;

      if (!file) {
        throw new Error('File field "myFile" is missing.');
      }

      const savePath = `./uploads/${file.name}`; // Store temporarily
      await file.mv(savePath); // Move file to destination

      return {
        fileName: file.name,
        size: file.size,
        description: input.description || 'No description',
        message: 'File uploaded successfully!',
      };
    }),
});

Client-side: Creating FormData

On the client, you'll typically use an HTML <input type="file"> element to allow users to select a file. To send this file, you'll create a FormData object.

FormData: A web API that lets you easily construct key-value pairs representing form fields and their values, including files.
Use formData.append('fieldName', value) to add data. For files, the value is the File object itself.

<!-- Example HTML snippet -->
<input type="file" id="fileInput" />
<script>
  const fileInput = document.getElementById('fileInput');
  
  function prepareFormData() {
    const file = fileInput.files[0];
    if (!file) {
      console.log('No file selected.');
      return null;
    }

    const formData = new FormData();
    // 'myFile' must match the field name expected by the server
    formData.append('myFile', file);
    formData.append('description', 'A document from the user.');

    console.log('FormData prepared!');
    return formData;
  }
</script>

Sending Files to the tRPC Endpoint

The standard tRPC client library isn't designed to send multipart/form-data directly for mutations. Instead, we typically use the native fetch API to send the FormData object to our tRPC endpoint.

The endpoint path will be /trpc/yourProcedureName, and the method will be POST.

Try running this example (ensure your server from Scene 5 & 7 is running):

<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
  <title>Upload File</title>
</head>
<body>
  <input type="file" id="fileInput" />
  <button onclick="uploadFile()">Upload</button>

  <script>
    async function uploadFile() {
      const fileInput = document.getElementById('fileInput');
      const file = fileInput.files[0];

      if (!file) {
        alert('Please select a file first.');
        return;
      }

      const formData = new FormData();
      formData.append('myFile', file); // 'myFile' matches server's expected name
      formData.append('description', 'A file from client!');

      try {
        const response = await fetch('http://localhost:3000/trpc/uploadFile', {
          method: 'POST',
          body: formData,
        });

        const result = await response.json();
        if (response.ok) {
          alert('Upload successful: ' + JSON.stringify(result));
        } else {
          alert('Upload failed: ' + JSON.stringify(result));
        }
      } catch (error) {
        console.error('Error uploading file:', error);
        alert('An error occurred during upload.');
      }
    }
  </script>
</body>
</html>

Quick Check

Which of the following statements are true about handling file uploads with tRPC?

Odpowiedz w interaktywnej lekcji

Recap & Next Steps

You've learned how to integrate file upload functionality into your tRPC application!

File uploads use multipart/form-data, requiring server-side parsing.
express-fileupload middleware on an Express server handles this parsing.
By applying the file upload middleware before tRPC middleware, req.files becomes available in your tRPC context.
Your tRPC mutation can then access and save the uploaded files.
On the client, use FormData and the native fetch API to send files to your tRPC endpoint.

Remember to consider robust file storage solutions (e.g., cloud storage like S3) and proper error handling for production applications.

Bezpłatny start

Ucz się tRPC End-to-End Type Safe APIs dzięki korepetycjom AI — za darmo

Pisz i uruchamiaj kod w przeglądarce, otrzymuj natychmiastową pomoc od korepetytora AI dostępnego 24/7 i kontynuuj naukę w sieci lub w aplikacji.

Kursy: 10
Lekcje: 40

Zacznij naukę bezpłatnie Wyświetl pełny kurs

Często zadawane pytania

Czy lekcja „Przesyłanie plików z tRPC” jest bezpłatna?

Tak — pełny tekst „Przesyłanie plików z tRPC” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu tRPC End-to-End Type Safe APIs, przejdź na CoddyKit PRO. Kurs tRPC End-to-End Type Safe APIs zawiera 4 lekcji w sumie.

Co nauczysz się w „Przesyłanie plików z tRPC”?

Zintegrują Państwo funkcję przesyłania plików z mutacjami tRPC, korzystając z multipart/form-data i odpowiednich parserów. Ćwiczysz tRPC End-to-End Type Safe APIs z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć tRPC End-to-End Type Safe APIs?

Nie wymagamy żadnego doświadczenia. tRPC End-to-End Type Safe APIs w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 3 z 4.

Ile czasu zajmuje lekcja „Przesyłanie plików z tRPC”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji tRPC End-to-End Type Safe APIs?

Tak. Każda lekcja tRPC End-to-End Type Safe APIs zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

Wydajne grupowanie żądań
Implementacja optymistycznych aktualizacji
Przesyłanie plików z tRPC
Zapytania nieskończone i stronicowanie oparte na kursorze

← Powrót do tRPC End-to-End Type Safe APIs