valaxy-addon-feishu

NPM version

English | 简体中文

Experimental — This addon and its API may change in future releases.

Feishu/Lark CMS integration for Valaxy via Content Loaders.

Fetches documents from Feishu (Lark) and converts them to Markdown, integrating seamlessly with Valaxy’s routing, search, and RSS pipelines.

Prerequisites ​

You need a Feishu self-built app with the following permissions:

  • docx:document:readonly — Read document content
  • wiki:wiki:readonly — Read wiki space (if using spaceId)
  • drive:drive:readonly — Download images (if using downloadImages)

Create an app at Feishu Open Platform.

Installation ​

bash
pnpm add valaxy-addon-feishu

Configuration ​

valaxy.config.ts
ts
import { defineValaxyConfig } from 'valaxy'
import { addonFeishu } from 'valaxy-addon-feishu'

export default defineValaxyConfig({
  addons: [
    addonFeishu({
      // Required: Feishu app credentials
      appId: process.env.FEISHU_APP_ID,
      appSecret: process.env.FEISHU_APP_SECRET,

      // Option A: Fetch all docs from a wiki space
      spaceId: 'your-wiki-space-id',

      // Option B: Fetch specific documents by ID
      // documents: ['doc-id-1', 'doc-id-2'],

      // Optional settings (shown with defaults)
      // prefix: 'posts',        // Output path: pages/posts/xxx.md
      // devPollInterval: 60000, // Re-fetch every 60s in dev mode
      // downloadImages: true,   // Download images to public/
      // imageDir: 'feishu-images', // Image output directory
    }),
  ],
})

Security: Never commit appId and appSecret directly. Use environment variables or .env files (add .env to .gitignore).

Options ​

OptionTypeDefaultDescription
appIdstringrequiredFeishu app ID
appSecretstringrequiredFeishu app secret
spaceIdstring—Wiki space ID to fetch all docs from
documentsstring[]—Specific document IDs to fetch
prefixstring'posts'Path prefix under pages/
devPollIntervalnumber60000Dev mode polling interval (ms)
downloadImagesbooleantrueDownload images to public/
imageDirstring'feishu-images'Subdirectory in public/ for images

You must provide at least one of spaceId or documents.

Supported Block Types ​

The addon converts Feishu document blocks to Markdown:

Block TypeOutput
TextParagraph
Heading 1–6# through ######
Heading 7–9Bold text (Markdown caps at h6)
Bullet list- item (nested)
Ordered list1. item (nested)
Code blockFenced code block with language
Quote> text
Todo- [x] / - [ ]
Divider---
Image![](url) (downloaded locally by default)
TableStandard | table
CalloutBlockquote with emoji
Equation$...$ inline math

Inline formatting: bold, italic, strikethrough, inline_code, links.

How It Works ​

  1. The addon injects a Content Loader via its setup() function
  2. Before Vite starts, the loader authenticates with Feishu using app credentials
  3. Documents are fetched (from wiki space and/or explicit IDs)
  4. Each document’s blocks are converted to Markdown
  5. Images are downloaded to public/{imageDir}/ and URLs are rewritten
  6. Markdown files with frontmatter are written to .valaxy/content/pages/{prefix}/
  7. Valaxy’s file-based routing picks them up automatically

Contributors