AVOID — Stale and unlicensed — last commit 4y ago

• 19 active contributors
• ⚠ Stale — last commit 4y ago
• ⚠ Concentrated ownership — top contributor handles 55% of recent commits
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows detected
• ⚠ No test directory detected
• ⚠ Scorecard: marked unmaintained (0/10)
• ⚠ Scorecard: default branch unprotected (0/10)

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

Ducks is a Redux design pattern and scaffolding specification that bundles action types, action creators, and reducers into self-contained modules called 'ducks'. It solves the fragmentation problem of Redux apps where related reducer logic, actions, and action types are scattered across separate files and folders, making code harder to maintain and reuse. Simple single-package structure: README.md and CommonJs.md contain the specification, duck.jpg and migrate.jpg are visual guides, and battlecry/generators/duck/ contains a Battlecry CLI generator for scaffolding new duck modules from templates (duck.generator.js uses naMe.js and configureStore.js templates).

Redux developers building JavaScript applications who want to organize their state management in a modular, co-located way. Specifically targets developers tired of context-switching between actions/, types/, and reducers/ directories, and library authors packaging reusable Redux logic.

This is a foundational pattern proposal from 2016 that remains influential in the Redux ecosystem, but the repo itself shows minimal recent activity (battlecry generator templates exist but appear dormant). It's stable doctrine rather than actively developed software — think of it as a specification with reference implementations rather than a constantly-evolving library.

Very low risk: the ducks pattern is convention-based with no external dependencies in the core proposal. The main risk is that this repo's battlecry generator (in battlecry/generators/duck/) appears unmaintained and may not generate modern Redux patterns (hooks, slices). The repo has no tests visible, which is typical for pattern documentation but limits confidence in the generated code.

No active development visible. This is a settled pattern specification. The battlecry generator is the only code artifact, but there's no evidence of recent changes, PRs, or issues being actively triaged.

This repo is primarily documentation: git clone https://github.com/erikras/ducks-modular-redux && cat README.md. If you want to use the Battlecry generator, install Battlecry CLI (npm install -g battlecry) then run battlecry generate duck in your project—but read the CommonJs.md example first to understand the pattern.

Daily commands: No dev server or build step. Read the pattern in README.md, see the example in CommonJs.md, then optionally use the Battlecry generator: npm install -g battlecry && battlecry generate duck. The repo is documentation + templates.

• README.md — Defines the Ducks proposal—the core architectural pattern that bundles reducers, action types, and actions into self-contained modules; essential for understanding the repo's purpose.
• battlecry/generators/duck/duck.generator.js — The code generator that scaffolds new Duck modules, enabling developers to follow the pattern consistently across the project.
• battlecry/generators/duck/templates/__naMe__.js — The template for generating a new Duck module; shows the canonical structure developers must follow when creating actionTypes, reducer, and action creators.
• battlecry/generators/duck/templates/configureStore.js — Demonstrates how to configure Redux store with Duck modules, showing the integration point between generated Ducks and the store setup.
• CommonJs.md — Provides a CommonJS variant example of the Ducks pattern; critical for developers using non-ES6 module systems.

• Duck Module (JavaScript/ES6, Redux) — Self-contained Redux slice containing action type constants, reducer function, and action creator functions
  • Failure mode: If reducer does not handle all dispatched actions or action types are not unique, store state updates may be incorrect or collide with other Ducks
• Battlecry Generator (Node.js, Battlecry framework) — Command-line tool that scaffolds new Duck modules from templates to enforce consistent structure
  • Failure mode: If templates are outdated or incorrect, generated Ducks may not follow the proposal pattern or lack required exports
• Redux Store Configuration (Redux, JavaScript) — Combines multiple Duck reducers and initializes the application state tree
  • Failure mode: If Ducks are not properly combined or store is misconfigured, state updates may not propagate or actions may be lost

• React Component → Duck Action Creator — Component calls an action creator exported from a Duck module
• Duck Action Creator → Redux Store — Action creator returns an action object that is dispatched to the Redux store
• Redux Store → Duck Reducer — Store passes current state and action to the appropriate Duck reducer based on action type
• Duck Reducer → Redux Store — Reducer returns new state slice, which is merged into the overall store state
• Redux Store → React Component — Component receives updated state and re-renders with new props

Create a new Duck module

1. Use the Battlecry generator to scaffold a new Duck by running a command that references the duck generator (battlecry/generators/duck/duck.generator.js)
2. The generator will create a new module file using the naMe template structure (battlecry/generators/duck/templates/__naMe__.js)
3. Define action type constants at the top (e.g., LOAD, CREATE, UPDATE, REMOVE) (battlecry/generators/duck/templates/__naMe__.js)
4. Implement the reducer function as the default export with your action handlers (battlecry/generators/duck/templates/__naMe__.js)
5. Export named action creator functions that dispatch your action types (battlecry/generators/duck/templates/__naMe__.js)

Integrate a Duck into the Redux store

1. Reference the configureStore template to understand store composition with Ducks (battlecry/generators/duck/templates/configureStore.js)
2. Import reducer and action creators from your Duck module (battlecry/generators/duck/templates/configureStore.js)
3. Combine Duck reducers using Redux combineReducers utility in your store configuration (battlecry/generators/duck/templates/configureStore.js)

Apply the Ducks pattern to an existing Redux codebase

1. Review the README.md to understand the bundling philosophy and why separate actionTypes/actions/reducer files should be consolidated (README.md)
2. For CommonJS projects, consult CommonJs.md for syntax and module.exports patterns (CommonJs.md)
3. Refactor existing action types, reducers, and action creators into self-contained Duck modules following the template structure (battlecry/generators/duck/templates/__naMe__.js)

• Redux — The Ducks pattern is a modularization proposal for Redux applications, requiring Redux as the state management foundation
• Battlecry Code Generator — Enables automated scaffolding of Duck modules, reducing boilerplate and ensuring consistent pattern adherence across projects
• ES6 Modules (with CommonJS alternative) — Primary example uses ES6 syntax for clarity; CommonJS variant provided for backward compatibility and broader adoption

• Bundle actionTypes, reducer, and actions in a single file per feature

  • Why: Improves code organization by keeping related Redux logic together, reducing file fragmentation
  • Consequence: Single Duck file may grow large for complex features; no separation of concerns by artifact type

• Namespaced action type strings (e.g., 'my-app/widgets/LOAD')

  • Why: Prevents action type collisions across different Ducks in large applications
  • Consequence: Slightly verbose action type definitions; requires discipline in naming conventions

• Proposal-based architecture rather than framework/library

  • Why: Keeps overhead minimal and allows integration into existing Redux projects without additional dependencies
  • Consequence: Pattern adoption relies on developer discipline; no runtime enforcement of Duck structure

• Does not provide middleware integration or side-effects handling (async actions remain developer responsibility)
• Does not enforce state immutability at runtime (relies on Redux and developer discipline)
• Does not manage selectors or memoization strategies
• Not a replacement for Redux—only a modularization proposal for how to organize Redux code

• Avg cyclomatic complexity: ~2 — This is a proposal/pattern repository with minimal runtime code; complexity is in documentation and templates rather than executable logic
• Largest file: README.md (120 lines)
• Estimated quality issues: ~0 — Repository is primarily documentation and code generation templates; actual runtime code is minimal and focused on demonstrating the pattern

• Scattered Redux artifacts (Medium) — README.md (motivation section): Keeping actionTypes, actions, and reducers in separate files or folders reduces cohesion and makes feature-level refactoring difficult
• Unnamespaced action types (High) — battlecry/generators/duck/templates/__naMe__.js: Action types without namespace prefixes (e.g., 'my-app/widgets/LOAD') risk collisions in large Redux apps with multiple Ducks

• battlecry/generators/duck/duck.generator.js (Tooling dependency) — Single code generator is the enforcement mechanism for Ducks pattern consistency; if outdated, new Ducks may not follow the proposal
• Redux combineReducers in configureStore.js template (Manual configuration) — All Duck reducers must be manually registered in the store configuration; no automatic discovery mechanism

The CommonJS example in README.md mentions a default import gotcha: when doing import * as widgetActions from './ducks/widgets', you'll accidentally import the reducer function as an action creator named default, which breaks. The README advises explicitly enumerating imports instead. The Battlecry generator requires Battlecry CLI to be globally installed and its templates may not align with modern Redux (no Redux Toolkit, Redux Query, etc.).

• Redux Action Types Namespacing — The Ducks spec requires action types like 'my-app/widgets/LOAD' with module path prefixes to avoid collisions; understanding this pattern prevents reducer cross-talk bugs
• Reducer Bundling / Module Co-location — Ducks bundles reducer, actions, and types in one file to reduce the boilerplate cost of adding features; this pattern directly influenced Redux Toolkit's design
• Action Creators as Serialization Layer — Ducks pattern treats action creators as the public API for dispatching—reducers and types are implementation details; this abstraction decouples calling code from action shape
• Middleware Composition with Ducks — Ducks modules can export side-effect creators (thunks, sagas, epics) alongside action creators; the spec acknowledges this extensibility without mandating a specific pattern
• Selector Co-location (implied by spec) — While not explicit in the Ducks rules, the pattern naturally extends to co-locating selectors with reducers for complete state slice encapsulation, reducing import chains
• Code Generation for Boilerplate (Battlecry pattern) — The repo includes a Battlecry generator demonstrating how scaffold tooling can enforce the Ducks pattern, reducing friction for new module creation

• reduxjs/redux-toolkit — Redux Toolkit (official) provides createSlice() which implements the ducks pattern natively with reducer + actions bundled, making external generators like Battlecry unnecessary
• redux-utilities/redux-starter-kit — Predecessor to Redux Toolkit; also bundled reducers and actions together, influenced by and aligned with the Ducks philosophy
• reduxjs/redux — Core Redux library that the Ducks pattern organizes; essential context for understanding why bundling was needed
• reduxjs/reselect — Canonical Redux companion library for memoized selectors; often co-located in duck modules for complete state-slice encapsulation
• redux-saga/redux-saga — Side effects library frequently paired with Ducks; examples in the spec mention exporting side effects like sagas from duck modules

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 unit tests for battlecry/generators/duck/duck.generator.js

The duck generator is a critical tool for scaffolding new ducks, but there are no visible test files in the repo. Adding tests would ensure the generator produces valid duck modules with correct action types, action creators, and reducer exports. This is especially important since the generator modifies the file system.

• [ ] Create battlecry/generators/duck/tests/duck.generator.test.js
• [ ] Test that generator creates a valid duck file with proper action types format (namespace/ACTION_TYPE)
• [ ] Test that generated reducer exports are functional and handle initial state correctly
• [ ] Test template variable substitution in battlecry/generators/duck/templates/naMe.js
• [ ] Test configureStore.js template generation for store setup

Complete the incomplete example in README.md

The README.md snippet shows the example stopping mid-proposal at the Reducer section. The incomplete code example makes it hard for new users to understand the full ducks pattern. Completing this with the reducer implementation, action creators, and a complete working example would significantly improve onboarding.

• [ ] Complete the widgets.js example showing the full reducer implementation with initial state
• [ ] Add action creator functions (load, create, update, remove) to the example
• [ ] Show the complete export statement bundling all three pieces together
• [ ] Add a usage example showing how to import and use the duck in a component
• [ ] Reference the CommonJs.md for alternate syntax examples

Add integration test for battlecry/generators/duck/templates/configureStore.js

The configureStore.js template is critical for setting up Redux in generated projects, but there's no test verifying it produces valid, functional store configurations. This template likely has dependencies on the generated duck files and should be tested to ensure generated stores actually work.

• [ ] Create battlecry/generators/duck/tests/configureStore.test.js
• [ ] Test that configureStore template generates code that properly combines reducers from multiple ducks
• [ ] Test that generated store can be imported and creates a valid Redux store instance
• [ ] Test middleware integration if configureStore template includes it
• [ ] Verify the generated store works with the reducer exported from duck template

• Write comprehensive tests for the Battlecry duck generator (battlecry/generators/duck/duck.generator.js): verify that generated modules export a reducer, action creators, and correctly-namespaced action types matching the Ducks spec rules.
• Create a TypeScript version of the ducks pattern and templates in battlcry/generators/duck/templates/ showing how to type action creators, reducers, and action payloads in a duck module.
• Add migration guide: document how existing Redux apps using separate actions/, reducers/, types/ folders can refactor to Ducks pattern, with before/after examples.

This is a Redux pattern/proposal library with minimal direct security risks. The codebase itself is architectural guidance rather than a runtime application. Primary concerns are: (1) inability to audit dependencies without package.json, (2) potential for the code generator to produce unsafe code if inputs aren't validated, and (3) lack of security documentation. The ducks pattern itself does not introduce inherent security vulnerabilities—security depends on how developers implement reducers and actions. The project appears well-maintained but would benefit from explicit security guidelines and dependency management visibility.

• Low · No package.json or dependency lock file provided — package.json / package-lock.json / yarn.lock. Without visibility into the project's dependencies, it is impossible to verify if any vulnerable packages are being used. Dependencies with known CVEs could be present. Fix: Provide dependency files and regularly audit packages using 'npm audit' or 'yarn audit'. Implement automated dependency scanning in CI/CD pipelines.
• Low · Code generator without input validation examples — battlecry/generators/duck/duck.generator.js. The battlecry code generator at 'battlecry/generators/duck/duck.generator.js' may generate code without proper validation. If user input is not sanitized, generated code could contain vulnerabilities. Fix: Implement strict input validation for all code generator templates. Ensure generated action types and reducer code cannot be exploited through malicious input.
• Low · No security documentation or guidelines visible — Repository root. The repository does not appear to have security guidelines, vulnerability disclosure policy, or security documentation visible in the provided structure. Fix: Add SECURITY.md file documenting responsible disclosure practices, security considerations for Redux ducks pattern, and best practices for secure reducer/action implementation.

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

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

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/erikras/ducks-modular-redux 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.

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

What it runs against: a local clone of erikras/ducks-modular-redux — 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 erikras/ducks-modular-redux | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 1591 days ago | Catches sudden abandonment since generation |

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

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

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

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "battlecry/generators/duck/duck.generator.js" \\
  && ok "battlecry/generators/duck/duck.generator.js" \\
  || miss "missing critical file: battlecry/generators/duck/duck.generator.js"
test -f "battlecry/generators/duck/templates/__naMe__.js" \\
  && ok "battlecry/generators/duck/templates/__naMe__.js" \\
  || miss "missing critical file: battlecry/generators/duck/templates/__naMe__.js"
test -f "battlecry/generators/duck/templates/configureStore.js" \\
  && ok "battlecry/generators/duck/templates/configureStore.js" \\
  || miss "missing critical file: battlecry/generators/duck/templates/configureStore.js"
test -f "CommonJs.md" \\
  && ok "CommonJs.md" \\
  || miss "missing critical file: CommonJs.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1591 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1561d)"
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/erikras/ducks-modular-redux"
  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).

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