Onboarding: framework7io/framework7

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/framework7io/framework7 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

WAIT — Single-maintainer risk — review before adopting

• Last commit 1w ago
• 5 active contributors
• MIT licensed
• CI configured
• ⚠ Single-maintainer risk — top contributor 96% of recent commits
• ⚠ No test directory detected

_{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 framework7io/framework7 repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/framework7io/framework7.

What it runs against: a local clone of framework7io/framework7 — 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 framework7io/framework7 | 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 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 37 days ago | Catches sudden abandonment since generation |

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "framework7io/framework7(\\.git)?\\b" \\
  && ok "origin remote is framework7io/framework7" \\
  || miss "origin remote is not framework7io/framework7 (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"

# 4. Critical files exist
test -f "gulpfile.js" \\
  && ok "gulpfile.js" \\
  || miss "missing critical file: gulpfile.js"
test -f "build/core/package.json" \\
  && ok "build/core/package.json" \\
  || miss "missing critical file: build/core/package.json"
test -f "babel.config.js" \\
  && ok "babel.config.js" \\
  || miss "missing critical file: babel.config.js"
test -f "kitchen-sink/core/js/app.js" \\
  && ok "kitchen-sink/core/js/app.js" \\
  || miss "missing critical file: kitchen-sink/core/js/app.js"
test -f ".github/CONTRIBUTING.md" \\
  && ok ".github/CONTRIBUTING.md" \\
  || miss "missing critical file: .github/CONTRIBUTING.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 37 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~7d)"
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/framework7io/framework7"
  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

Framework7 is a full-featured HTML/CSS/JS framework for building native-like iOS and Android mobile apps using web technologies. It provides pre-built UI components (toolbars, navbars, modals, forms, etc.), touch-optimized interactions, and routing—packaged into Core, Vue, Svelte, and React variants so you can build hybrid apps without Cordova/Capacitor boilerplate. Monorepo with framework-agnostic Core at root (src/ with DOM7, components, modules) and flavor-specific builds under build/{core,vue,svelte,react}/, each with own package.json. kitchen-sink/ contains runnable demo apps for each flavor. Build system uses Gulp (gulpfile.js) to transpile via Babel configs (babel-vue.config.js, babel-svelte.config.js, babel-react.config.js, babel.config.js) and output ESM bundles.

Who it's for

Mobile app developers (both iOS and Android users) who want to ship cross-platform apps using HTML/CSS/JS instead of native languages, and who prefer framework-agnostic core (vanilla JS) or Vue/Svelte/React bindings. Also targets agencies building branded mobile web apps quickly.

Maturity & risk

Highly mature and actively maintained: the 2.5M+ LOC JavaScript codebase, presence of four parallel framework flavors (Core/Vue/Svelte/React), CI/CD via GitHub Actions (.github/workflows/), and Patreon funding model indicate production-grade stability. The monorepo structure (build/core, build/vue, build/svelte, build/react) with separate package.json per flavor shows thoughtful architecture for long-term support.

Low risk for established projects, moderate risk for greenfield: the framework is opinionated (mobile-first, iOS/Android target), so retargeting to web or desktop requires significant rework. Dependency on framework7.io docs (not fully visible here) creates documentation-as-a-service risk. The large codebase (2.5M JS) and four-flavor maintenance burden could slow bug fixes if the core team shrinks.

Active areas of work

The repository is actively maintained with parallel development across multiple framework flavors. Recent activity includes Vue, Svelte, React, and Core-specific issue templates (.github/ISSUE_TEMPLATE/), GitHub Actions workflows for issue management (issue-labeled.yml, issue-close-require.yml), and Prettier/ESLint enforcement (.prettierrc, .eslintrc.js). The CHANGELOG.md and CONTRIBUTING.md suggest ongoing feature additions and community contributions.

Get running

git clone https://github.com/framework7io/framework7.git
cd framework7
npm install
npm run build

Then explore kitchen-sink/core (or kitchen-sink/vue, kitchen-sink/svelte, kitchen-sink/react) to run flavor-specific demos.

Daily commands:

npm install
npm run build
cd kitchen-sink/core && npm install && npm start

Or for Vue: cd kitchen-sink/vue && npm install && npm start. Exact dev server command inferred from kitchen-sink subproject scripts (not fully visible, check kitchen-sink/*/package.json).

Map of the codebase

• gulpfile.js — Build orchestration for all framework variants (core, React, Vue, Svelte); entry point for compilation pipeline
• build/core/package.json — Core framework package definition; defines the primary framework7 distribution and its dependencies
• babel.config.js — Base Babel configuration for transpiling ES6+ across all builds; affects code compatibility and output
• kitchen-sink/core/js/app.js — Primary demo application showing all framework features; canonical usage patterns for contributors
• .github/CONTRIBUTING.md — Contributor guidelines including development workflow, testing, and submission standards
• README.md — Project overview, feature list, and documentation links; context for understanding framework scope
• package.json — Monorepo root configuration; defines workspace structure for core, React, Vue, and Svelte variants

Components & responsibilities

• Gulp Build System — Orchestrates multi-variant compilation; reads babel configs, invokes Babel transpiler, outputs framework7.es

How to make changes

Add a new UI component page to Kitchen Sink

1. Create a new HTML file in the pages directory with component markup and demo content (kitchen-sink/core/pages/[component-name].html)
2. Add route definition mapping the URL path to the new component page (kitchen-sink/core/js/routes.js)
3. Add menu link to the main navigation list to make component discoverable (kitchen-sink/core/pages/home.html)
4. Implement component logic and initialization in app.js if interactive features needed (kitchen-sink/core/js/app.js)

Build and publish a new framework variant (e.g., Angular)

1. Create new variant package directory matching existing pattern (build/[framework-name]/package.json)
2. Add variant-specific Babel configuration following naming convention (babel-[framework-name].config.js)
3. Create Gulp build task for variant compilation in main build orchestrator (gulpfile.js)
4. Create Nova editor task for development workflow consistency (.nova/Tasks/[FrameworkName].json)

Enforce code quality standards across variants

1. Configure formatting rules in root prettier configuration (.prettierrc)
2. Update ESLint ignore patterns for new files or directories (.eslintignore)
3. Review and update ESLint rules affecting all variants (.eslintrc.js)
4. Add variant-specific linting rules in build configuration if needed (build/[variant]/package.json)

Add assets (fonts, images) to Kitchen Sink

1. Place font files (TTF/WOFF/WOFF2) in fonts directory (kitchen-sink/core/fonts/[font-name].[extension])
2. Place image assets in img directory with descriptive naming (kitchen-sink/core/img/[image-name].jpg)
3. Reference assets in HTML pages or CSS with correct relative paths (kitchen-sink/core/css/app.css)
4. Verify assets load in demo by testing routes in Kitchen Sink app (kitchen-sink/core/js/routes.js)

Why these technologies

• Gulp — Multi-variant build orchestration; enables parallel compilation of core and framework-specific wrappers (React, Vue, Svelte)
• Babel — ES6+ transpilation with framework-specific presets; ensures compatibility across target platforms and variant runtimes
• Monorepo structure (package.json workspaces) — Unified dependency management and consistent tooling across core, React, Vue, and Svelte variants
• GitHub Actions workflows — Automated CI/CD for PR validation, issue management, and stale issue cleanup
• Kitchen Sink demo app — Single source of truth for API contracts and feature documentation; ensures all components work end-to-end

Trade-offs already made

• Single Kitchen Sink demo for core variant only (no React/Vue/Svelte demos in file list)

  • Why: Reduces maintenance burden; framework-agnostic component showcase demonstrates core library correctly
  • Consequence: React/Vue/Svelte wrapper variants require separate documentation or external demos; slightly higher barrier for variant-specific adoption

• Babel transpilation instead of native ES modules for distribution

  • Why: Ensures broad browser compatibility and older JavaScript runtime support
  • Consequence: Slightly larger bundle size; transpilation adds build time; less direct source-to-output mapping for debugging

• Monorepo with separate build/ subdirectories per variant

  • Why: Clear separation of concerns; each variant has isolated package.json and dependencies
  • Consequence: Multiple build steps required; potential for version skew between variants if not carefully managed

Non-goals (don't propose these)

• Real-time collaboration or multiplayer features
• Backend API or server-side rendering
• Native iOS/Android compilation (HTML-to-native bridge)
• Machine learning or AI-driven components
• Offline-first database synchronization

Traps & gotchas

No visible tests directory: The 2.5M LOC JavaScript codebase appears to lack Jest/Mocha test files in the provided file list—verify if tests live elsewhere (e.g., src/**/*.spec.js not shown) before assuming untested code. Four Babel configs to keep in sync: Changes to transpilation (e.g., new JS features) must be applied to babel.config.js AND babel-vue.config.js AND babel-svelte.config.js AND babel-react.config.js or flavor-specific builds silently diverge. kitchen-sink subprojects have own dependencies: Each kitchen-sink/{flavor} has its own package.json and npm install phase; forgetting to run them locally causes demo startup failures. DOM7 dependency: The framework includes a custom DOM library (mentioned in sideEffects) instead of relying on native or jQuery—this is non-standard and could surprise contributors.

Architecture

Concepts to learn

• DOM7 — Framework7's custom lightweight DOM library (mentioned in sideEffects) replaces jQuery and underpins all component interactions; understanding its API is critical for modifying or extending components
• Web Components / Custom Elements — Framework7 uses a component-based architecture similar to Web Components; each UI element (navbar, modal, form) is a self-contained module with props/slots/lifecycle
• Monorepo with framework flavors — The Core/Vue/Svelte/React split is a multi-framework monorepo pattern; you must understand which flavor you're modifying and how changes propagate through build/{flavor}/
• Touch event handling and gesture recognition — iOS/Android apps rely on swipe, pinch, long-press gestures; Framework7 bakes these into core (e.g., Swiper, Gestures modules) rather than relying on click events
• View / Router abstraction — Mobile apps use a stack-based navigation model (push/pop pages) rather than SPA-style history; Framework7 implements a custom View/Router to handle this paradigm
• Less CSS preprocessing — The framework uses Less (476KB) for themability and maintainability across 4 flavors; understanding Less variables and mixins is essential for styling changes
• ESM (ECMAScript Modules) as primary distribution — framework7.esm.js is the main export with sideEffects declared for Less/CSS; understanding tree-shaking and how sideEffects affect bundler behavior is critical for users and contributors

Related repos

• ionic/ionic — Competing iOS/Android app framework using Stencil + Angular; similar UI component library and mobile-first approach
• nativescript/nativescript — Alternative cross-platform mobile framework using native rendering instead of WebView; different architecture but targets same iOS/Android developer audience
• framework7io/framework7-react — Official React flavor of Framework7 maintained as a companion repo; contains React-specific bindings and examples
• react-native/react-native — Contrasting approach: React Native compiles to native code rather than WebView, but targets same cross-platform mobile use case
• thoriumbuilder/thorium — Visual builder for Framework7 apps (referenced in README as sponsor); companion tooling for visual app design atop this framework

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 GitHub Actions workflow for multi-framework test coverage (React, Vue, Svelte)

The repo has framework-specific babel configs (babel-react.config.js, babel-vue.config.js, babel-svelte.config.js) and separate build directories (build/react, build/vue, build/svelte), but only .travis.yml for CI. Modern GitHub Actions workflows are missing for testing framework-specific builds and ensuring cross-framework compatibility. This would catch framework-specific regressions early.

• [ ] Create .github/workflows/test-react.yml to run React-specific tests against build/react/package.json
• [ ] Create .github/workflows/test-vue.yml to run Vue-specific tests against build/vue/package.json
• [ ] Create .github/workflows/test-svelte.yml to run Svelte-specific tests against build/svelte/package.json
• [ ] Reference existing .nova/Tasks/*.json to identify the correct build/test commands for each framework
• [ ] Ensure workflows run on PR and commits to catch framework-specific regressions

Add TypeScript definition tests for framework7.d.ts

The package.json declares 'typings': 'framework7.d.ts' but there's no visible test coverage validating that TypeScript definitions match actual runtime exports. This is critical for TS users and prevents definition drift. Adding dtslint or tsd tests would catch breaking type changes.

• [ ] Create tests/ or src/tests/types/ directory structure
• [ ] Add tsd or dtslint tests validating framework7.d.ts exports against actual build output
• [ ] Test framework variants (core, react, vue, svelte) have correct type exports
• [ ] Add GitHub Action workflow .github/workflows/test-types.yml to run type tests on PR

Add missing kitchen-sink examples for less-commonly-used framework7 components

The kitchen-sink/core directory exists with some examples, but has gaps. The repo supports iOS & Android apps but kitchen-sink lacks comprehensive component coverage for all framework7 modules. New contributors can fill in missing interactive examples to improve discoverability and help users learn the framework.

• [ ] Audit kitchen-sink/core/pages/ against all components exported in the core build to identify missing examples
• [ ] Create missing page files for undocumented components (e.g., Stepper, Messagebar, Autocomplete detailed examples)
• [ ] Add routes to kitchen-sink/core/js/routes.js linking to new pages
• [ ] Test examples work in both iOS and Android modes using kitchen-sink/core/index.html

Good first issues

• Add ESLint test coverage for kitchen-sink/{svelte,react} example files to ensure demo apps follow the same linting rules as src/; currently only Core/Vue demos appear lint-checked.
• Document the Babel transpilation matrix: create a ARCHITECTURE.md or BUILD.md file explicitly mapping which babel-*.config.js file is used for which flavor output, since the four separate configs are error-prone for contributors unfamiliar with the monorepo.
• Create a minimal test stub or describe the testing strategy in CONTRIBUTING.md: the absence of visible test files in the file list suggests either missing tests or tests housed elsewhere; clarify this for new contributors so they know whether to add tests for their changes.

Top contributors

• @nolimits4web — 96 commits
• @nyxkn — 1 commits
• @stanleyxu2005 — 1 commits
• @xxxCam900xxx — 1 commits
• @DAnn2012 — 1 commits

Recent commits

• 075f38a — 9.0.4 (nolimits4web)
• 35cc53e — chore: deps (nolimits4web)
• 540f7eb — feat(types): types for css exports (nolimits4web)
• 301df42 — chore: sponsors (nolimits4web)
• 6503a57 — Update FUNDING.yml (nolimits4web)
• 7168e1c — chore: sponsors (nolimits4web)
• 2a6cdd7 — 9.0.3 (nolimits4web)
• ce78c34 — fix(dialog): fix button color ignored in iOS theme (nolimits4web)
• d8e8167 — fix(calendar): fix dateFormat overrides (nolimits4web)
• 4881641 — fix(popover): restore scrolling on popover by disabling touch highlight on it (nolimits4web)

Security observations

Framework7 shows a reasonable security posture for an open-source HTML framework. The main concerns are: (1) outdated CI/CD tooling (Travis CI), (2) lack of visible security policy and responsible disclosure process, (3) potential XSS risks inherent to DOM manipulation frameworks without visible mitigation strategies, and (4) incomplete visibility into dependency security. The framework maintains good development practices (ESLint, GitHub workflows) but should enhance security documentation and vulnerability management processes. No critical vulnerabilities detected from the available file structure, but runtime security depends on proper usage and regular dependency updates.

• Medium · Outdated CI/CD Configuration — .travis.yml. The repository uses Travis CI (.travis.yml) which has been deprecated and is no longer maintained. This could lead to missed security updates and vulnerabilities in the CI/CD pipeline. Fix: Migrate to GitHub Actions (already partially present in .github/workflows) or another actively maintained CI/CD platform. Ensure all workflows have security scanning enabled.
• Medium · Missing Security Headers Configuration — Framework configuration (not visible in provided structure). No visible security headers configuration (Content-Security-Policy, X-Frame-Options, etc.) in the framework configuration or documentation. This is important for a framework used to build mobile apps. Fix: Document and provide default security headers configuration. Consider adding CSP and X-Frame-Options middleware examples in kitchen-sink demo.
• Low · Potential DOM Manipulation Risk — shared/dom7.js, kitchen-sink examples. The codebase includes 'shared/dom7.js' as a sideEffect in package.json, and the framework is used for HTML/DOM manipulation. Without visible code review, there's potential for XSS vulnerabilities if user input is directly rendered to DOM. Fix: Conduct security audit of DOM manipulation functions. Ensure all user inputs are properly sanitized before DOM insertion. Use textContent instead of innerHTML where possible.
• Low · Missing Security Policy Documentation — Repository root. No visible SECURITY.md file for responsible disclosure of security vulnerabilities. Security contact information is not apparent. Fix: Create a SECURITY.md file following GitHub's security policy template with responsible disclosure guidelines and security contact information.
• Low · Incomplete Dependency Security Information — build/core/package.json, build/react/package.json, build/svelte/package.json, build/vue/package.json. The package.json provided is minimal and doesn't show all dependencies. Cannot verify if outdated or vulnerable packages are used. Fix: Maintain an updated package.json with all dependencies. Use 'npm audit' regularly and keep dependencies updated. Consider using Dependabot or Snyk for automated vulnerability scanning.
• Low · No Subresource Integrity (SRI) Guidance — Documentation (not visible in provided structure). No visible SRI hash guidance for CDN-served assets, which could impact security for end users of the framework. Fix: Provide SRI hash values for all distributed CDN assets. Document how users should verify integrity of downloaded framework files.

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.