Onboarding: dvajs/dva

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/dvajs/dva 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
• 26+ active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 9mo ago
• ⚠ Concentrated ownership — top contributor handles 66% 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 dvajs/dva repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dvajs/dva.

What it runs against: a local clone of dvajs/dva — 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 dvajs/dva | 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 ≤ 303 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>dvajs/dva</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dvajs/dva. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dvajs/dva.git
#   cd dva
#
# 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 dvajs/dva and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "dvajs/dva(\\.git)?\\b" \\
  && ok "origin remote is dvajs/dva" \\
  || miss "origin remote is not dvajs/dva (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 303 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~273d)"
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/dvajs/dva"
  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

Dva is a lightweight Redux and React framework that applies Elm-style architecture (models with reducers, effects, and subscriptions) to JavaScript SPAs. It reduces Redux boilerplate by providing a declarative model system, async effect handling via redux-saga, and automatic state management—used as the foundation for Umi.js and enterprise dashboards like Ant Design Pro. Monorepo structure: packages/ contains dva-core and plugins like dva-loading; examples/func-test/ is a runnable demo using Roadhog build tool. Source models in src/models/ follow Elm-style object shape: namespace, state, reducers (sync), effects (async generators), subscriptions. State updates via dispatch(action) routed through reducers or saga-backed effects.

Who it's for

React developers building single-page applications who want Redux's predictability without the boilerplate, and teams adopting Umi.js (where Dva is the default state layer). Particularly enterprise teams building admin dashboards and data-driven UIs.

Maturity & risk

Production-ready and actively maintained. The repo has 9.5k+ GitHub stars, CI/CD via CircleCI and GitHub Actions, comprehensive test coverage tracked with codecov, and is used in major projects like Ant Design Pro. However, the ecosystem is older (ES6-era tooling like Roadhog, Babel 6) and development has slowed relative to 2015–2018 peaks.

Medium risk: dependencies on redux-saga (which has its own learning curve and can hide complexity in generator functions) and react-router v4/v5 (version locked in examples). The project is singular-maintainer-adjacent; while not abandoned, release frequency is lower than contemporary frameworks. Breaking changes between v1 and v2 exist. Consider that Umi.js now abstracts Dva away entirely, reducing direct adoption.

Active areas of work

Repository appears in maintenance mode. CircleCI and GitHub Actions run on commits. Recent activity likely focused on compatibility patches for React 16+ and dependency updates rather than feature development. The example at examples/func-test/ demonstrates current best practices.

Get running

git clone https://github.com/dvajs/dva.git
cd dva
npm install
cd examples/func-test
npm install
npm start  # Starts Roadhog dev server on http://localhost:8000

Daily commands:

cd examples/func-test
npm start  # Roadhog dev server with HMR
npm run build  # Production build
npm run lint  # ESLint check

Map of the codebase

• packages/dva-core/src/index.js: Core library entry point; defines create() and plugin architecture that wraps Redux store and redux-saga middleware.
• examples/func-test/src/models/example.js: Canonical model example showing namespace, state, reducers, effects, and subscription patterns.
• docs/guide/getting-started.md: Primary user-facing guide explaining Elm concepts, model structure, and API.
• [.eslintrc and .eslintrc (examples/func-test/)](https://github.com/dvajs/dva/blob/master/.eslintrc and .eslintrc (examples/func-test/)): Project linting config (Airbnb style) enforced across core and examples.
• [.circleci/config.yml and .github/workflows/ci.yml](https://github.com/dvajs/dva/blob/master/.circleci/config.yml and .github/workflows/ci.yml): CI/CD configuration; defines test, lint, and build validation pipeline.

How to make changes

Adding a new feature: create a model in examples/func-test/src/models/ following the namespace/state/reducers/effects pattern, dispatch actions from components via connect(). Fixing a bug: locate the affected model or index.js entry point in packages/ (core API), write a test in test/, verify with examples/func-test/. Documentation: edit docs/ folder using Vuepress (see .vuepress/config.js). For core library changes: modify src/ in the root, not examples.

Traps & gotchas

Node version: examples pin 6.9.2 in package.json engines (very old); likely needs update to 12+. Roadhog is unmaintained: build tool is ancient; switch to create-react-app or Umi.js for new projects. Generator functions in effects: redux-saga uses function*/ yield syntax—unintuitive for developers unfamiliar with generators or async/await; no TypeScript support in core. No built-in HMR: requires babel-plugin-dva-hmr and explicit setup; Umi.js handles this automatically. Model namespace uniqueness: duplicate namespaces silently fail; no validation at definition time.

Concepts to learn

• Elm Architecture (Model-View-Update) — Dva's core design pattern: models separate state (state), state updates (reducers), side effects (effects), and external subscriptions. Understanding this paradigm is essential to using Dva idiomatically.
• Redux Middleware — Dva initializes Redux store with redux-saga middleware injected; understanding middleware lets you intercept and transform actions before they hit reducers.
• Redux-Saga (Generator Functions and Effects) — Dva's effects are redux-saga generators (function* / yield); mastering saga patterns (put, call, take) is required to handle async logic, race conditions, and cancellation.
• Action Dispatch and Reducer Pure Functions — Dva enforces Redux discipline: actions must be dispatched, reducers must be pure (no side effects). Violations break predictability and HMR.
• Hot Module Replacement (HMR) with Babel Plugin — Dva supports HMR via babel-plugin-dva-hmr for models and components; enables fast feedback but requires explicit plugin setup and can mask stale closure bugs.
• Plugin System (Aspect-Oriented Middleware) — Dva app.use(plugin) hooks into model registration and effect execution; plugins like dva-loading augment behavior without modifying core. Core extensibility pattern.
• React Context and Connect (Redux Connector) — Dva uses react-redux connect() to subscribe components to state; understanding mapStateToProps and mapDispatchToProps is required for every connected component.

Related repos

• facebook/redux — Core state management library that Dva wraps; understanding Redux reducers and dispatch is prerequisite knowledge.
• redux-saga/redux-saga — Saga middleware used by Dva for handling effects; effects in Dva models are generator functions using redux-saga.
• umijs/umi — Modern React framework that abstracts Dva as its default state layer; Umi users don't directly interact with Dva API but benefit from its patterns.
• ant-design/ant-design-pro — Enterprise dashboard template built on Dva; demonstrates idiomatic Dva usage at scale with async requests, loading states, and complex routing.
• dvajs/dva-loading — Official Dva plugin for automatic loading state management; commonly used companion to handle UI loading indicators.

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.

Add comprehensive unit tests for dva core modules

The repo has CircleCI and codecov configured but the test coverage appears incomplete. The examples in examples/func-test/src/models/example.js and examples/user-dashboard/ suggest active model/reducer patterns but there's no visible test/ or __tests__/ directory with comprehensive specs. New contributors can add unit tests for core dva utilities (model creation, reducer composition, effect handling) which would directly improve codecov metrics and reliability.

• [ ] Create test/ directory structure mirroring src/ layout
• [ ] Add unit tests for src/index.js (main dva export and app initialization)
• [ ] Add tests for reducer composition and effect middleware handling
• [ ] Add tests for model registration validation and namespace conflict detection
• [ ] Ensure tests run in CircleCI via existing .circleci/config.yml

Migrate from deprecated Roadhog to modern build tooling and update example configuration

Both examples use roadhog (^1.2.0) which is unmaintained. The .umirc.js in user-dashboard suggests migration toward umi, but func-test still uses .roadhogrc configs. A new contributor can modernize the build setup by either updating to umi or webpack 5, removing outdated babel plugins like babel-plugin-module-alias, and simplifying package.json dependencies to use current tooling standards.

• [ ] Update examples/func-test/.roadhogrc to .umirc.js configuration format
• [ ] Remove deprecated dependencies: roadhog, babel-plugin-module-alias, redbox-react
• [ ] Update babel-plugin-dva-hmr to compatible version or replace with modern HMR solution
• [ ] Update build scripts in both example package.json files to use umi or webpack
• [ ] Verify examples still run with npm start and npm run build

Add TypeScript definitions and stricter ESLint configuration for type safety

The repo uses older ESLint configs (eslint-config-airbnb@13.0.0, babel-eslint@7.1.1) and has no visible TypeScript support or .d.ts files despite being a framework library. Modern typescript usage is widespread; adding type definitions and updating ESLint would help new users and contributors catch errors earlier. This involves creating proper type exports and updating linting rules.

• [ ] Create src/index.d.ts with TypeScript definitions for main dva exports (app, model, connect utilities)
• [ ] Add typescript and @types/react, @types/redux to devDependencies
• [ ] Update .eslintrc to use modern config and add TypeScript parser support
• [ ] Update babel-eslint to @babel/eslint-parser in package.json
• [ ] Add TypeScript checking to .circleci/config.yml test workflow

Good first issues

• Add TypeScript type definitions for the core API in packages/dva-core/src/. Currently no .d.ts files exist; start with index.ts for create(), model(), and plugin() exports.: Blocks TypeScript adoption for teams evaluating Dva; aligns with modern React practices.
• Expand examples/func-test/ to include error handling in effects (try/catch saga patterns) and a real async API call (currently no network requests shown). Add docs/guide/error-handling.md.: Current example is too minimal; beginners struggle with actual async patterns and don't know how to handle API failures.
• Modernize examples/func-test/ build tooling: replace Roadhog with create-react-app or Umi.js, update Node engine to 14+, and upgrade React to 18.x. Update babel config to drop babel-runtime transpilation.: Examples are a barrier to entry; old build tooling confuses newcomers and doesn't reflect current React ecosystem.

Top contributors

• @sorrycc — 66 commits
• @DiamondYuan — 5 commits
• @xc1427 — 2 commits
• @ycjcl868 — 2 commits
• @zhanba — 2 commits

Recent commits

• b60e6c0 — docs: remove dvajs.com references (#2523) (sorrycc)
• 7490ae9 — Publish (sorrycc)
• b02daba — feat: support react 18 (#2515) (jasonzhuang)
• 968da6a — Publish (sorrycc)
• 11b27a1 — chore: publish > release (sorrycc)
• 554827e — chore: add __isDvaPatch args for the initial history listen handler call (#2511) (sorrycc)
• 64996cb — Publish (sorrycc)
• 1a8c9b3 — fix: invalid dva-loading peerDependencies spec (#2510) (gemwuu)
• 3eaee30 — Publish (sorrycc)
• e0ccd09 — feat(dva-immer): upgrade immer to 8 (#2431) (sorrycc)

Security observations

The codebase presents significant security concerns due to severe outdatedness. Dependencies are from 2016-2017 with known vulnerabilities, and Node.js 6 is no longer supported or patched. The entire stack (dva, roadhog) is deprecated. Critical

• High · Outdated Dependencies with Known Vulnerabilities — package.json (dependencies and devDependencies). The project uses significantly outdated dependencies from 2016-2017 era. Babel 6.x, ESLint 3.x, and other build tools have known security vulnerabilities and are no longer maintained. This includes babel-runtime@6.9.2, eslint@3.12.2, and roadhog@1.2.0 which have multiple disclosed CVEs. Fix: Update all dependencies to their latest stable versions. Minimum versions: babel@7.x+, eslint@8.x+, react@18.x+ (or at least 16.13.1+), and modern build tools. Run 'npm audit' and address all reported vulnerabilities.
• High · Node.js Version Constraint Outdated — package.json (engines field). The engines field specifies 'install-node': '6.9.2', which is Node.js 6 from 2016. This version reached end-of-life in April 2019 and contains numerous security vulnerabilities. No security patches are available. Fix: Update to Node.js 18.x LTS or higher. Modify engines field to: "node": ">=18.0.0" and ensure all dependencies are compatible with modern Node versions.
• Medium · Missing Dependency Pinning Strategy — package.json. Dependencies use caret (^) and tilde (~) version ranges without a lock file visible in the structure. This allows automatic installation of patch and minor versions that could introduce breaking changes or vulnerabilities without explicit review. Fix: Ensure package-lock.json or yarn.lock is committed to version control. Consider using npm ci instead of npm install in CI/CD pipelines. Review and test all dependency updates before deployment.
• Medium · Babel Configuration Not Visible — Root directory (missing .babelrc or babel.config.js). No .babelrc or babel.config.js file is visible in the provided structure. This could indicate reliance on deprecated .roadhogrc configuration for Babel settings, making security and compatibility checks difficult. Fix: Create explicit babel.config.js file with current Babel 7+ syntax. Document all Babel plugins and presets. Remove dependency on roadhog which is deprecated.
• Medium · No Security Headers or CSP Configuration — examples/ (missing security config). No .webpackrc.js or webpack configuration visible with security headers, Content Security Policy, or Subresource Integrity settings. The examples don't demonstrate secure default configurations. Fix: Add webpack plugins for security headers. Implement Content Security Policy headers. Use security-focused webpack plugins like webpack-subresource-integrity.
• Low · Unencrypted Mock Configuration — examples/func-test/.roadhogrc.mock.js. File '.roadhogrc.mock.js' suggests mock API configuration. If this contains sensitive test data or credentials, it could be exposed through version control. Fix: Ensure mock files never contain real credentials or sensitive data. Use environment-based configuration for test data. Add *.mock.js to .gitignore if sensitive.
• Low · Deprecated Framework Stack — project-wide (framework choice). The entire dva framework and its dependencies (roadhog, etc.) are deprecated and no longer maintained. The project recommends migration to umi.js for new projects. Fix: Plan migration to umi.js or modern frameworks (Next.js, Vite with React). If continuing with dva, implement additional security monitoring and vulnerability scanning.
• Low · No HTTPS Configuration Visible — .circleci/config.yml, package.json scripts. CircleCI configuration and development server setup don't show explicit HTTPS enforcement or security protocol configuration. Fix: Ensure production deployments use HTTPS. Configure build pipeline to enforce secure protocols. Add HSTS headers in production deployment.

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.