Onboarding: dream-num/Luckysheet

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/dream-num/Luckysheet shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across all four use cases

• Last commit 9mo ago
• 13 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 9mo ago
• ⚠ Concentrated ownership — top contributor handles 59% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live dream-num/Luckysheet repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dream-num/Luckysheet.

What it runs against: a local clone of dream-num/Luckysheet — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in dream-num/Luckysheet | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 290 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>dream-num/Luckysheet</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dream-num/Luckysheet. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dream-num/Luckysheet.git
#   cd Luckysheet
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of dream-num/Luckysheet and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "dream-num/Luckysheet(\\.git)?\\b" \\
  && ok "origin remote is dream-num/Luckysheet" \\
  || miss "origin remote is not dream-num/Luckysheet (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 290 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~260d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/dream-num/Luckysheet"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Luckysheet is an open-source online spreadsheet editor (similar to Excel/Google Sheets) written in JavaScript with jQuery, supporting formulas, charts, pivot tables, and collaborative editing. However, the project is no longer actively maintained — the team has migrated to Univer (a TypeScript rewrite) which adds import/export, printing, and improved formula calculation. Monolithic single-package build: source lives in src/ (inferred), compiled to dist/ (UMD, ESM, CJS) via Gulp + Rollup. Documentation is in docs/ using VuePress 1.x. Build outputs are dist/luckysheet.umd.js (browser), dist/luckysheet.esm.js (modules), dist/luckysheet.cjs.js (Node.js). No visible src/ directory structure in file list, suggesting classic pre-ES6 module layout.

Who it's for

Web developers and enterprises building browser-based data entry and analysis tools who need an Excel-like UI without commercial licensing. Used by teams deploying self-hosted spreadsheet solutions via the Luckysheet Server (Java backend) or Node.js integration layers.

Maturity & risk

Luckysheet reached v2.1.13 and was production-ready, but is now in maintenance-only mode. The README explicitly states 'Luckysheet is no longer maintained' and recommends migrating to Univer for new projects. CI/CD exists (.github/workflows for builds and docs), but commit velocity has likely slowed since the Univer fork. Not recommended for new production deployments.

High risk for new projects: official guidance is to use Univer instead. Dependencies are dated (jQuery 2.2.4, Babel 7.12.x from 2020, Rollup 2.32 from 2020) with minimal updates. The codebase is 7.2MB JavaScript with Gulp/Rollup build tooling that may have security rot. No visible test suite in file list suggests low test coverage. Single maintenance team (dream-num org) with uncertain long-term support.

Active areas of work

Project is in sunset mode: the CHANGELOG.md and issue #1454 document the migration to Univer. GitHub Actions workflows (github-demo.yml, github-doc.yml) handle automated demo builds and documentation deployments. Gitee mirror sync is active (gitee-mirror.yml), suggesting continued mirror maintenance but no new feature development.

Get running

Clone the repo, install dependencies with npm, then run dev server:

git clone https://github.com/dream-num/Luckysheet.git
cd Luckysheet
npm install
npm run dev

For documentation: npm run docs:dev starts a local VuePress server on docs/.

Daily commands: Development: npm run dev (spawns Gulp watch + Browser-sync dev server). Production: npm run build (outputs to dist/). Documentation: npm run docs:dev (VuePress on http://localhost:8080).

Map of the codebase

• package.json: Defines all build scripts (dev, build, docs), dependencies (jQuery, Numeral, Flatpickr), and output targets (UMD/ESM/CJS). Entry point for understanding the build pipeline.
• dist/luckysheet.umd.js: The compiled production bundle consumed by web applications; understanding dist/ layout is crucial for integration patterns.
• docs/.vuepress/config.js: VuePress configuration for the documentation site; defines sidebar structure, plugins (Baidu autopush, code copy, SEO, sitemap), and build settings.
• README.md: Critical context: explicitly states the project is unmaintained and recommends Univer for new deployments. Points to all ecosystem repos (Vue, React, Node, Java backend).
• .github/workflows/: GitHub Actions pipelines (gitee-mirror.yml, github-demo.yml, github-doc.yml) automate builds, docs generation, and mirror syncs; indicates active CI/CD but not active feature development.
• CHANGELOG.md: Documents the full version history and migration message; essential for understanding what was built and where the project ended.

How to make changes

Start in src/ (structure not fully visible, but likely src/index.js as entry). For UI/formula changes, look for cell handler logic. For styling, CSS lives in top-level directories (216KB CSS total). Add docs by editing Markdown in docs/guide/ (English) or docs/zh/guide/ (Chinese). For build changes, edit gulpfile.js and rollup.config.js. Contribute via commitizen-style commits (npm run commit).

Traps & gotchas

No explicit src/ directory structure visible in file list — the actual source files are likely in a non-obvious location (possibly a 'src' folder not listed, or pre-compiled). Build output is dist/ with three formats (UMD/ESM/CJS) — ensure you target the correct bundle format. VuePress 1.x is used for docs, not 2.x, so version-specific plugins apply. Prettier formatting is enforced (npm run prettier:fix) — PRs must pass linting. The project has commitlint rules (commitlint.config.js) requiring conventional commits. Gulp build requires cross-env for NODE_ENV to work cross-platform. No visible test directory or test commands — no automated test suite.

Concepts to learn

• Sparse Matrix Representation — Spreadsheets store millions of cells but most are empty. Luckysheet must optimize memory by storing only non-empty cells and their references, a core challenge in online sheet engines.
• Formula Recalculation Engine (DAG) — Cell formulas create dependencies (A1 depends on B1+C1); Luckysheet must maintain a dependency graph and topologically sort updates. Univer claims to improve this vs. Luckysheet.
• Operational Transformation (OT) for Collaboration — The 'cooperative editing demo' mentioned in the README requires OT or CRDTs to merge concurrent edits. Understanding how concurrent changes are serialized is critical for the Luckysheet Server backend.
• UMD/ESM/CJS Module Formats — Luckysheet builds three output formats (dist/luckysheet.umd.js, .esm.js, .cjs.js) via Rollup; understanding which to use for browsers vs. Node.js vs. bundlers is essential for integration.
• Virtual Scrolling (Viewport Rendering) — A spreadsheet with 1M rows cannot render all cells in the DOM. Luckysheet uses virtual scrolling to render only visible cells, a pattern critical for performance.
• Rollup Module Bundling — The build pipeline uses Rollup 2 + Babel to transform ES6 source to CJS/ESM/UMD. Understanding Rollup config is needed to add dependencies or change build outputs.
• Gulp Task Automation — Gulp 4 orchestrates CSS minification, code concatenation, and asset management. The dev and build scripts run Gulp pipelines; modifying build behavior requires editing gulpfile.js.

Related repos

• dream-num/univer — Official successor: TypeScript rewrite with import/export, printing, and collaboration. Recommended for all new projects per the README.
• mengshukeji/luckysheet-vue — Official Vue 2 integration for Luckysheet; shows how to embed the spreadsheet in Vue CLI 3 projects.
• mengshukeji/luckysheet-react — Official React integration; demonstrates wrapping Luckysheet for React applications.
• mengshukeji/Luckyexcel-node — Node.js backend for Luckysheet; handles file I/O and data import/export in server environments.
• SheetJS/sheetjs — Industry standard for Excel file parsing in JavaScript; Luckysheet and successors likely depend on or complement it for import/export.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Create migration guide and automated scripts for Luckysheet to Univer transition

Since the README explicitly states Luckysheet is no longer maintained and recommends Univer as the upgraded version, the repo should provide concrete migration documentation and tooling. Currently, there's no docs/guide/migration.md or docs/zh/guide/migration.md explaining how users can transition their Luckysheet implementations to Univer. This is critical for existing users and adds real value during the sunset period.

• [ ] Create docs/guide/migration.md with step-by-step migration instructions from Luckysheet API to Univer API
• [ ] Create docs/zh/guide/migration.md with Chinese translation
• [ ] Add a migration-helper utility script in src/ that maps old Luckysheet config objects to Univer equivalents
• [ ] Document breaking changes and deprecated APIs in the migration guide with code examples

Add GitHub Actions workflow for automated dependency vulnerability scanning

The repo has .github/workflows/ with demo and doc workflows, but lacks security scanning. With dependencies like jquery@2.2.4 (outdated), pako, and esbuild, automated vulnerability detection would catch security issues early. This is especially important for a UI library that handles spreadsheet data.

• [ ] Create .github/workflows/security-scan.yml using npm audit or snyk action
• [ ] Configure the workflow to run on push to main and on pull requests
• [ ] Set up failure conditions for high/critical vulnerabilities in package.json dependencies
• [ ] Add status badge to README.md showing security scan status

Extract and test gulpfile.js build pipeline with unit tests

The gulpfile.js orchestrates the entire build process (babel, uglify, concat, css minification) but has no test coverage. Given the complexity of the build pipeline with multiple output formats (cjs, esm, umd in package.json), contributors could easily break builds. Adding tests would document expected behavior and catch regressions.

• [ ] Create src/tests/gulpfile.test.js using jest or mocha to test gulp task outputs
• [ ] Add tests verifying each output format (dist/luckysheet.cjs.js, .esm.js, .umd.js) is generated correctly
• [ ] Test that CSS minification in gulp-clean-css produces valid output
• [ ] Add pre-commit hook via husky to run build tests before merge

Good first issues

• Add missing TypeScript definitions: The dist/ outputs are untyped JavaScript. Create a luckysheet.d.ts file documenting the public API (cell, sheet, data APIs from docs/guide/api.md) to help TypeScript users. Start by extracting method signatures from docs/guide/
• Migrate VuePress documentation to v2.x and fix outdated plugins: docs/.vuepress/config.js uses VuePress 1.5.0 with deprecated plugins. Upgrade to VuePress 2.x, replace deprecated SEO/sitemap plugins with maintained alternatives, and test local builds (npm run docs:build).
• Add Prettier formatting pass and document style guide: The codebase has a .prettierrc.json but the file list shows no style guide docs. Document in CONTRIBUTING.md the expected code style, run npm run prettier:fix on an entire src/ directory, and ensure CI enforces it.

Top contributors

• @Dushusir — 59 commits
• @tonytonychopper123 — 29 commits
• @gphwxh — 2 commits
• @wpxp123456 — 1 commits
• @jikkai — 1 commits

Recent commits

• 5b3fe58 — docs: link (Dushusir)
• e0b5591 — docs: short link for univer (Dushusir)
• bf1b632 — docs: update univer link (Dushusir)
• 3f38973 — fix: univer link (Dushusir)
• 60bdffd — chore: README.md (wpxp123456)
• b418f33 — docs: remove qq qrcode, add link to univer (Dushusir)
• 4767c13 — docs: add sponsors (Dushusir)
• 9399854 — docs: update README (jikkai)
• 418a210 — fix(api): conditionName typo error (Dushusir)
• a8a259b — fix(formula): formula calculate bug (Dushusir)

Security observations

• High · Outdated jQuery Dependency with Known Vulnerabilities — package.json - dependencies.jquery: ^2.2.4. The project uses jQuery 2.2.4, which is severely outdated (released 2016) and contains multiple known security vulnerabilities including XSS and prototype pollution issues. jQuery 2.2.4 is no longer maintained and has been superseded by jQuery 3.x series with security patches. Fix: Upgrade to jQuery 3.6.x or latest stable version. If possible, consider replacing jQuery with modern vanilla JavaScript or a more maintained alternative like Vue.js or React components already in use.
• High · Outdated Babel Runtime Dependencies — package.json - devDependencies and dependencies. Dependencies use @babel/runtime-corejs3 ^7.12.1 and @babel/runtime ^7.12.1 from late 2020. These versions are outdated and may contain security vulnerabilities in the polyfills and runtime helpers. Fix: Update @babel/runtime and @babel/runtime-corejs3 to the latest stable version (currently 7.23.x). Run 'npm audit' to identify and fix security issues.
• High · Potential XSS Vulnerability via escape-html Usage — src/controllers/ (especially formulaBar.js, ifFormulaGenerator.js, cellFormat.js). The project includes 'escape-html' dependency but without reviewing actual code usage patterns in controllers and handlers, there's risk of improper HTML escaping especially in formula bar, cell rendering, and formula generation (ifFormulaGenerator.js). If user input is processed without proper escaping before DOM insertion, XSS attacks are possible. Fix: Audit all user input handling in cell content, formulas, and hyperlinks. Ensure consistent use of escape-html or DOMPurify for all untrusted content. Never use innerHTML with user-provided data; use textContent or sanitized content.
• High · Unmaintained Project Status — README.md. The README explicitly states 'Luckysheet is no longer maintained' and recommends using Univer instead. No active security patches will be provided for discovered vulnerabilities. This is a critical risk for production deployment. Fix: Migrate to the maintained Univer fork (https://univer.short.gy/LuckysheetRepository) for production use. Do not deploy unmaintained Luckysheet in production environments handling sensitive data.
• Medium · Outdated Development Dependencies — package.json - devDependencies (vuepress, rollup, gulp suite, etc.). Multiple dev dependencies are outdated including vuepress ^1.5.0 (last updated 2020), rollup ^2.32.1 (from 2020), and others. These may contain security vulnerabilities in the build pipeline. Fix: Update all dev dependencies to latest stable versions. Consider upgrading to VuePress 2.x if documentation uses Vue 3. Run 'npm audit --audit-level=moderate' regularly during development.
• Medium · Potential CSV/Formula Injection in Data Handling — src/controllers/ (alternateformat.js, ifFormulaGenerator.js, filter.js). The project appears to handle spreadsheet data including formulas (ifFormulaGenerator.js, filter.js) and alternate formats. Without proper validation, malicious formulas starting with '=', '+', '-', or '@' could lead to formula injection attacks when exported/imported. Fix: Implement formula injection protection: sanitize formula strings by prepending single quotes for formulas, validate input against whitelist of safe formula patterns, and add warnings for potentially dangerous formulas.
• Medium · Configuration File Exposure Risk — src/config.js. src/config.js is included in version control without clear indication of what sensitive data it might contain. Config files should not contain credentials, API keys, or secrets. Fix: Audit src/config.js to ensure no hardcoded secrets, API keys, or credentials. Use environment variables for all sensitive configuration. Add config.js patterns to .gitignore for environment-specific configs.
• Medium · Unverified Third-Party Data Validation — undefined. dataVerificationCtrl.js handles data validation but without reviewing the code, there's risk of accepting malicious Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.