DDYS API Astro Integration

中文

ddys-astro is the official Astro integration for the DDYS API. It injects Astro pages, API endpoints, server helpers, .astro components, a content loader, SEO routes, diagnostics, secure request-form handling, icons, and ready-to-copy examples.

Installation

npm install ddys-astro

Add the integration:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import ddys from 'ddys-astro';

export default defineConfig({
  output: 'server',
  integrations: [
    ddys({
      mountPath: '/ddys',
      apiPrefix: '/api/ddys'
    })
  ]
});

output: 'server' is required for injected DDYS pages, API endpoints, sitemap, request forms, and Astro.locals.ddys middleware.

Static Astro projects can still use the components, content loader, styles, packaged icons, robots.txt, and manifest.webmanifest. Runtime DDYS pages and API routes are skipped automatically in static builds so the integration does not force a server adapter.

Environment

DDYS_API_BASE_URL=https://ddys.io/api/v1
DDYS_SITE_BASE_URL=https://ddys.io
DDYS_API_KEY=
DDYS_FORM_SECRET=
DDYS_REQUEST_FORM_ENABLED=false
DDYS_DIAGNOSTICS_ENABLED=false
DDYS_REVALIDATE_TOKEN=

Keep DDYS_API_KEY, DDYS_FORM_SECRET, and DDYS_REVALIDATE_TOKEN server-only. Do not expose them as public client variables.

Integration Features

• Uses the Astro Integration API and astro:config:setup.
• Injects pages under /ddys by default.
• Injects API endpoints under /api/ddys by default.
• Registers Astro.locals.ddys through middleware.
• Injects Astro.locals.ddys TypeScript declarations during astro:config:done.
• Serves icons copied from the DDYS public icon set at /ddys-astro/images.
• Keeps static Astro builds adapter-free by only prerendering static-safe assets, robots, and manifest routes.
• Ships a content loader for Astro Content Collections.
• Ships SEO helpers for metadata, sitemap, robots, manifest, and Movie JSON-LD.

Injected Pages

• /ddys
• /ddys/latest
• /ddys/hot
• /ddys/movies
• /ddys/search
• /ddys/calendar
• /ddys/movie/[slug]
• /ddys/movie/[slug]/sources
• /ddys/collections
• /ddys/shares
• /ddys/types
• /ddys/genres
• /ddys/regions
• /ddys/request
• /ddys/diagnostics

API Endpoints

• GET /api/ddys/proxy
• GET /api/ddys/request
• POST /api/ddys/request
• GET /api/ddys/diagnostics
• POST /api/ddys/diagnostics
• POST /api/ddys/revalidate
• GET /sitemap.xml
• GET /robots.txt
• GET /manifest.webmanifest

The proxy uses an allow-list before mapping routes to the DDYS API.

Components

---
import DdysView from 'ddys-astro/components/DdysView';
import DdysSearch from 'ddys-astro/components/DdysSearch';
import DdysRequestForm from 'ddys-astro/components/DdysRequestForm';
import 'ddys-astro/styles.css';
---

<DdysView view="latest" params={{ limit: 12 }} />
<DdysSearch />
<DdysRequestForm />

Available components:

• DdysView
• DdysGrid
• DdysCard
• DdysMovieDetail
• DdysSources
• DdysSearch
• DdysRequestForm
• DdysDiagnostics

Server Client

import { createDdysServerClient } from 'ddys-astro/server';

const client = createDdysServerClient();
const latest = await client.latest({ limit: 12 });

The client covers movies, latest, hot, search, suggest, calendar, movie, sources, related, comments, collections, collection, shares, share, requests, activities, user, types, genres, regions, me, createRequest, createComment, deleteComment, reportInvalidResource, follow, and unfollow.

Astro.locals.ddys is available in server-rendered routes when the integration middleware is enabled. Its TypeScript declaration is injected only for output: 'server' with middleware on, so static projects and middleware: false projects do not get a false runtime guarantee.

---
const latest = await Astro.locals.ddys.latest({ limit: 12 });
---

Browser Proxy Client

import { DdysProxyClient } from 'ddys-astro/client';

const ddys = new DdysProxyClient('/api/ddys');
const hot = await ddys.hot({ limit: 12 });

The proxy client calls the injected Astro API endpoints, so DDYS secrets stay server-side.

Content Loader

// src/content/config.ts
import { defineCollection, z } from 'astro:content';
import { createDdysContentLoader } from 'ddys-astro/content';

export const collections = {
  ddys: defineCollection({
    loader: createDdysContentLoader({ view: 'latest', limit: 50, params: { type: 'movie' } }),
    schema: z.object({
      title: z.string().optional(),
      slug: z.string().optional()
    }).passthrough()
  })
};

Request Form

Enable it only when an API key is configured:

DDYS_API_KEY=...
DDYS_FORM_SECRET=...
DDYS_REQUEST_FORM_ENABLED=true

The form validates title, year, type, Douban ID, IMDb ID, honeypot field, CSRF token, and rate limits before calling the authenticated DDYS API.

Development Checks

pnpm typecheck
node tools/check.mjs
node --test tests/structure.test.mjs
pnpm build
pnpm pack --dry-run
powershell -ExecutionPolicy Bypass -File tools/build-package.ps1 -Version 0.1.2

The source ZIP is generated at dist/ddys-astro-v0.1.2.zip.