Services

strapi2front generates type-safe service functions for all your content types. These services handle API communication with your Strapi backend.

Service Structure

Each content type gets a service with these methods:

export const articleService = {
  findMany,  // List with filters, returns { data, pagination }
  findAll,   // Fetch ALL entries (handles pagination automatically)
  findOne,   // Get by documentId
  create,    // Create new entry
  update,    // Update existing entry
  delete,    // Delete entry
};

findMany (Paginated List)

Retrieve multiple entries with optional filters, pagination, and sorting. Returns paginated response with data and pagination metadata.

import { articleService } from "@/strapi/collections/article/service";

// Get first page of articles
const { data: articles, pagination } = await articleService.findMany();

// With pagination
const { data: page1, pagination } = await articleService.findMany({
  pagination: { page: 1, pageSize: 10 },
});

// With filters
const { data: published } = await articleService.findMany({
  filters: {
    publishedAt: { $notNull: true },
    title: { $contains: "TypeScript" },
  },
});

// With sorting
const { data: latest } = await articleService.findMany({
  sort: ["publishedAt:desc", "title:asc"],
});

// With relations (populate)
const { data: withAuthor } = await articleService.findMany({
  populate: ["author", "categories"],
});

// Complex populate
const { data: detailed } = await articleService.findMany({
  populate: {
    author: { fields: ["name", "email"] },
    categories: { populate: ["icon"] },
  },
});

findAll (All Entries)

Fetch ALL entries automatically handling pagination. Useful when you need every item.

// Get ALL articles (handles pagination internally)
const allArticles = await articleService.findAll();

// With filters - gets all matching items
const allPublished = await articleService.findAll({
  filters: { publishedAt: { $notNull: true } },
});

// With relations
const allWithAuthors = await articleService.findAll({
  populate: ["author"],
});

Caution

Use findAll() carefully with large datasets. It makes multiple API requests to fetch all pages.

findOne

Get a single entry by its documentId.

import { articleService } from "@/strapi/collections/article/service";

// Get by documentId
const article = await articleService.findOne("abc123xyz");

// With specific fields
const article = await articleService.findOne("abc123xyz", {
  fields: ["title", "content"],
});

// With relations
const article = await articleService.findOne("abc123xyz", {
  populate: ["author", "categories"],
});

create

Create a new entry.

import { articleService } from "@/strapi/collections/article/service";

const newArticle = await articleService.create({
  title: "My New Article",
  slug: "my-new-article",
  content: "Article content here...",
});

// With relations
const articleWithAuthor = await articleService.create({
  title: "New Article",
  content: "Content...",
  author: "authorDocumentId",
  categories: ["cat1", "cat2"],
});

// With draft status (Strapi v5)
const draft = await articleService.create(
  { title: "Draft Article", content: "..." },
  { status: "draft" }
);

update

Update an existing entry.

import { articleService } from "@/strapi/collections/article/service";

const updated = await articleService.update("abc123xyz", {
  title: "Updated Title",
});

// Partial updates (only changed fields)
const updated = await articleService.update("abc123xyz", {
  content: "New content only",
});

// Update with status change
const published = await articleService.update(
  "abc123xyz",
  { title: "Final Title" },
  { status: "published" }
);

delete

Delete an entry.

import { articleService } from "@/strapi/collections/article/service";

await articleService.delete("abc123xyz");

Filtering

Strapi supports powerful filtering operators:

const { data: filtered } = await articleService.findMany({
  filters: {
    // Equality
    status: "published",

    // Comparison
    views: { $gt: 100 },
    rating: { $gte: 4 },
    stock: { $lt: 10 },
    price: { $lte: 99.99 },

    // String matching
    title: { $contains: "guide" },
    slug: { $startsWith: "how-to" },
    email: { $endsWith: "@example.com" },

    // Null checks
    publishedAt: { $notNull: true },
    deletedAt: { $null: true },

    // Array membership
    category: { $in: ["tech", "science"] },
    status: { $notIn: ["draft", "archived"] },

    // Logical operators
    $or: [
      { status: "published" },
      { featured: true },
    ],
    $and: [
      { views: { $gt: 100 } },
      { rating: { $gte: 4 } },
    ],
  },
});

Population (Relations)

Control which relations are loaded:

Simple

// Array of relation names
const { data: articles } = await articleService.findMany({
  populate: ["author", "categories"],
});

Nested

// Nested population
const { data: articles } = await articleService.findMany({
  populate: {
    author: {
      populate: ["avatar", "socialLinks"],
    },
    categories: {
      fields: ["name", "slug"],
    },
  },
});

Deep

// Deep population with filters
const { data: articles } = await articleService.findMany({
  populate: {
    comments: {
      filters: { approved: true },
      sort: ["createdAt:desc"],
      populate: {
        author: {
          fields: ["name"],
        },
      },
    },
  },
});

Localization (i18n)

For content types with i18n enabled:

// Get content in specific locale
const { data: spanishArticles } = await articleService.findMany({
  locale: "es",
});

// Get all localizations
const article = await articleService.findOne("abc123", {
  populate: ["localizations"],
});

Draft & Publish

For content types with draft/publish enabled:

// Get only published (default)
const { data: published } = await articleService.findMany({
  status: "published",
});

// Get drafts
const { data: drafts } = await articleService.findMany({
  status: "draft",
});

// Create as draft
const draft = await articleService.create(
  { title: "Work in Progress" },
  { status: "draft" }
);

// Publish a draft
const published = await articleService.update(
  "abc123",
  {},
  { status: "published" }
);

Error Handling

Services throw errors for failed requests:

try {
  const article = await articleService.findOne("invalid-id");
} catch (error) {
  if (error.status === 404) {
    console.log("Article not found");
  } else {
    console.error("API error:", error.message);
  }
}

Client Configuration

Services use a shared client configured with your Strapi URL and token from environment variables.

Tip

The client handles authentication, request formatting, and response parsing automatically.

User Authentication (Beta)

Caution

This feature is in beta and the API may change in future versions.

By default, services use STRAPI_TOKEN from your environment. For user-authenticated requests (e.g., after login), you can pass clientOptions to any service method:

import { articleService } from "@/strapi/collections/article/service";

// Default: uses STRAPI_TOKEN
await articleService.findMany();

// With user JWT token
await articleService.findMany(
  { filters: { author: userId } },
  { authToken: session.jwt }
);

// Create as authenticated user
await articleService.create(
  { title: "My Post", content: "..." },
  { authToken: userJwt }
);

// Update with user token
await articleService.update(
  "abc123",
  { title: "Updated" },
  { authToken: userJwt }
);

// Delete with user token
await articleService.delete("abc123", { authToken: userJwt });

ClientOptions

All service methods accept an optional clientOptions parameter:

interface ClientOptions {
  /** JWT token or API token for authentication */
  authToken?: string;
  /** Base URL of the Strapi instance (for multi-tenant setups) */
  baseURL?: string;
}

Creating a Reusable Client

For multiple operations with the same token, create a client instance:

import { createStrapiClient } from "@/strapi/shared/client";

// Create client with user token
const userClient = createStrapiClient({ authToken: session.jwt });

// Use the client directly
const articles = await userClient.collection("articles").find();
const homepage = await userClient.single("homepage").find();

Multi-tenant Setup

For applications connecting to different Strapi instances:

// Connect to a different Strapi instance
await articleService.find(
  {},
  {
    baseURL: "https://tenant-a.strapi.example.com",
    authToken: tenantToken,
  }
);