Skip to content

README.md

Latest commit

 

History

History
81 lines (53 loc) · 4.9 KB

README.md

File metadata and controls

81 lines (53 loc) · 4.9 KB
Raw

Univer Office SDK Documentation

This is the official documentation site for Univer Office SDK, which includes Web SDK, Server SDK, and AI SDK, built with Next.js, Fumadocs headless content tooling, and project-owned UI.

Prerequisites

Local Development

Install dependencies:

pnpm install

Start the development server:

pnpm dev

The site will be available at http://localhost:3030.

Build for production:

pnpm build

The Icons preview, MCP endpoint, and downloadable metadata use public/assets/icons/catalog.json. To refresh it from a matching univer-icons checkout, run node scripts/sync-icons-catalog.mjs ../univer-icons. The sync checks that the source and installed package versions match and that every exported icon is covered. Production builds use the committed catalog.

The read-only Icons MCP runs at /mcp/icons in the existing Next.js Node server. It exposes search_icons and get_icon over Streamable HTTP without a model API key or separate process. Its Host/Origin allowlist covers docs.univer.ai and loopback hosts; update app/mcp/icons/route.ts when deploying under another hostname. With the site running, verify the endpoint using DOCS_TEST_ORIGIN=http://localhost:3030 node --test app/mcp/icons/__tests__/route.spec.mjs.

Showcase

Showcase source, assets, tests and build tooling live in the sibling ../office.univer.ai Vite project. Run pnpm dev there, then set NEXT_PUBLIC_SHOWCASES_ORIGIN=http://localhost:5180 here. Production example links and embedded previews default to https://office.univer.ai. Set NEXT_PUBLIC_SHOWCASES_ORIGIN in .env.local to override that address for local development.

Project Structure

├── app/              # Next.js application routes and layouts
├── components/       # React components for the documentation site
├── content/          # Documentation content (MDX)
│   ├── blog/         # Blog posts
│   ├── guides/       # Web SDK: editors, product features, and Icons (/guides)
│   ├── server/       # Server SDK: collaboration and server-side file exchange (/server)
│   ├── ai/           # AI SDK: agent operations, CLI, and Worktree (/ai)
│   └── reference/    # API reference
├── examples/         # Framework integration examples (React, Vue, Angular, Astro)
├── lib/              # Utility libraries
├── public/           # Static assets
└── scripts/          # Build and automation scripts

Product import/export feature guides stay in content/guides/<product>/features; server conversion, storage, and integration guides live in content/server/import-export.

Contributing

We welcome contributions to the documentation. Please ensure your changes follow the existing style and conventions. Run pnpm lint and pnpm typecheck before submitting.

For more information about contributing to Web SDK, see the main repository.

Deploy Using ECS

The site's built-in editors read the GitHub Actions secret CLIENT_LICENSE_TEXT at build time. Configure it in this repository's Settings → Secrets and variables → Actions, or in the selected deployment environment. For local development, copy .env.example to .env.local and set CLIENT_LICENSE_TEXT there.

The ⬆️ Deploy workflow passes the secret through Make and a Docker BuildKit secret mount. Next.js exposes it as NEXT_PUBLIC_CLIENT_LICENSE_TEXT, which the editors pass to UniverLicensePlugin. This is a client license and is included in browser JavaScript. Updating it requires building and deploying a new image; deploying an existing image does not change its license. Image builds require a non-empty license and rerun the application build to pick up secret changes.

The ECS workflow sends client_license_text to runner-machine. Its execute_task_documentation job must forward that field as CLIENT_LICENSE_TEXT in the remote command's environment before calling make push_image. The corresponding receiver change must be deployed in runner-machine before using this workflow. Embedded Showcase demos run on office.univer.ai and use that site's own license configuration.

To deploy the documentation site to ECS through GitHub Actions:

  1. Open Actions and select 🕶️ Deploy Using ECS.
  2. Select the branch to deploy (for example, dev).
  3. Set Environment to deploy to staging or international.
  4. Select the ACR registry region: use cn-shenzhen for the staging environment, or us-east-1 for the international environment.
  5. Enter the required ECS instance size (for example, 32c64g) and click Run workflow.

The workflow dispatches the deployment to runner-machine; the ECS region is derived from the selected ACR region (cn-shenzhen → shenzhen, us-east-1 → us-virginia).