Onboarding: amfe/lib-flexible

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/amfe/lib-flexible 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

AVOID — Stale and unlicensed — last commit 3y ago

• 2 active contributors
• ⚠ Stale — last commit 3y ago
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 71% of recent commits
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows detected
• ⚠ 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 amfe/lib-flexible repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/amfe/lib-flexible.

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

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>amfe/lib-flexible</code></summary>

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

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

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

# 4. Critical files exist
test -f "index.js" \\
  && ok "index.js" \\
  || miss "missing critical file: index.js"
test -f "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "index.min.js" \\
  && ok "index.min.js" \\
  || miss "missing critical file: index.min.js"

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

amfe-flexible is a responsive layout library that scales rem (root em) units dynamically based on viewport width, enabling flexible mobile-first designs without media queries. It calculates and injects a root font-size value into the <html> element that adapts to screen size, allowing CSS developers to write designs in rem units that automatically scale proportionally across devices. Single-file library structure: index.js contains the core REM-scaling logic and is bundled to index.min.js via UglifyJS. No monorepo, no package structure—the entire implementation is one executable JavaScript file meant to be inlined or linked in the <head> before any CSS renders.

Who it's for

Mobile web developers at Alibaba and elsewhere building responsive Chinese-language sites who need rem-based flexible layouts without writing viewport-specific CSS. Primarily teams using postcss-adaptive tooling to convert px designs to rem automatically.

Maturity & risk

Mature but deprecated: v2.2.1 released, no test suite visible in repo, no CI configuration evident. The library itself is production-stable (used at Alibaba scale), but the README explicitly recommends migrating to CSS viewport units (vw/vh) as a superior modern standard, indicating this is in legacy-maintenance mode rather than active development.

Low technical risk but deprecation risk is real: the author's README warns the project is a 'transition solution' with 'certain issues' and recommends switching to viewport units instead. Single file (index.js at 1139 LOC), zero dependencies, no automated test coverage—maintenance burden is minimal but adoption of new projects should be discouraged. Last activity not visible in provided data.

Active areas of work

Repository appears dormant. Version 2.2.1 is current, with only UglifyJS compression script in package.json. No active PRs, milestones, or recent commits visible from provided metadata. The deprecation notice in README is the primary signal—library is in 'end of life' advisory mode.

Get running

git clone git@github.com:amfe/lib-flexible.git
cd lib-flexible
npm install
npm run compress  # generates index.min.js from index.js

Daily commands: No dev server. Link or inline index.js (or index.min.js) in your HTML <head> before any stylesheets:

<script src="./node_modules/amfe-flexible/index.js"></script>

No npm start or development command exists; modifications require editing index.js directly.

Map of the codebase

• index.js — Core entry point that implements the flexible layout logic by dynamically calculating and setting rem unit based on viewport width; every contributor must understand this file's viewport scaling algorithm
• package.json — Defines project metadata, build scripts (uglify compression), and establishes this as an npm package meant for mobile responsive design
• README.md — Documents the deprecated status of lib-flexible in favor of viewport units, usage instructions, and integration guidance for developers evaluating this library
• index.min.js — Production-ready minified version of the core logic generated by uglifyjs; this is the actual artifact deployed to npm and used in HTML script tags

Components & responsibilities

• Viewport detection & calculation (JavaScript DOM API) — Reads clientWidth, applies scaling formula, and sets root font-size
  • Failure mode: If viewport detection fails (unusual), rem scaling does not initialize; page layout breaks on all responsive units
• Event listener management (JavaScript addEventListener) — Attaches resize/orientationchange handlers to keep rem base synchronized with screen dimensions
  • Failure mode: If listeners don't fire or are throttled poorly, layout won't adapt on rotation or resize; memory leaks possible if not cleaned up

Data flow

• Browser viewport → lib-flexible script — Provides window.innerWidth / clientWidth to determine current screen size
• lib-flexible script → DOM html element — Writes calculated rem base (e.g., '10px') to html.style.fontSize
• DOM html element → CSS rem units — CSS engine uses html font-size as the reference value for all rem-based measurements in page stylesheets

How to make changes

Modify viewport scaling algorithm

1. Open index.js and locate the main calculation logic that reads viewport width and sets the rem base size on the html element (index.js)
2. Update the scaling formula (e.g., change from 10px per 375px viewport to a different ratio) in the core resize/init handler (index.js)
3. Run npm run compress to regenerate index.min.js with your changes (package.json)
4. Test by embedding the new index.min.js in an HTML file with the required viewport meta tag (index.min.js)

Integrate lib-flexible into a new project

1. Install via npm: npm i -S amfe-flexible (package.json)
2. Add required viewport meta tag to HTML head (README.md)
3. Include index.min.js script tag in HTML before other stylesheets and scripts, or inline it for optimal performance (index.min.js)
4. Use postcss-adaptive or similar tools to convert px to rem in your CSS during build time (README.md)

Why these technologies

• Plain JavaScript (ES5 compatible) — No external dependencies; minimal file size; needs to execute before main styles load; high browser compatibility on mobile
• npm package distribution — Enables easy installation and version management for projects that require flexible rem-based scaling
• UglifyJS minification — Reduces production bundle size from ~1–2KB to ~500–800 bytes, critical for inline scripts in mobile HTML heads

Trade-offs already made

• Use rem units with dynamic font-size calculation instead of native viewport units

  • Why: Older Android browsers and legacy mobile devices lack full vw/vh support; rem polyfills JavaScript-based scaling across more devices
  • Consequence: Extra JS execution overhead on page load and resize; README now recommends viewport units as modern alternative, indicating this approach is deprecated

• Single, monolithic index.js file instead of modular architecture

  • Why: Script must execute early in page load before CSS applies; dependencies and modules would complicate inline embedding and delay layout calculation
  • Consequence: Harder to extend or test in isolation; all logic coupled in one function; minimal reusability

Non-goals (don't propose these)

• Does not support server-side rendering or progressive enhancement beyond basic mobile responsiveness
• Does not provide cross-browser font-scaling shims for IE or very old Android devices
• Not a CSS framework; does not include pre-built components or layout helpers
• Does not handle font-size override collisions if user CSS also sets root font-size

Code metrics

• Avg cyclomatic complexity: ~2 — Single-purpose utility with straightforward viewport read, arithmetic calculation, and DOM write; no branching or state management complexity
• Largest file: index.js (80 lines)
• Estimated quality issues: ~2 — Global side effects and tight coupling between calculation and DOM mutation; minimal error handling or validation of viewport values

Anti-patterns to avoid

• Global side effects in top-level script (Medium) — index.js: Code modifies global DOM state (html.style.fontSize) immediately on execution without guards; can conflict with other scripts or user CSS if not inlined early enough
• Tight coupling between viewport calculation and DOM update (Low) — index.js: No separation of concerns; calculation logic and DOM mutation are intertwined, making it hard to test or adapt scaling formula independently

Performance hotspots

• index.js - Resize event handler (Layout thrashing / performance) — Every window resize triggers full recalculation and DOM update; no debouncing or throttling, can cause excessive reflows on fast resize
• Script execution timing (Page load / blocking) — Script must run synchronously before CSS and layout; blocking execution adds to page load critical path if not inlined

Traps & gotchas

No environment variables or runtime config—the library auto-detects everything from window object; behavior is hardcoded in index.js. Inlining requirement: must be loaded synchronously in <head> before CSS to prevent FOUC (flash of unstyled content) when REM values are first applied. No tree-shaking or module exports—entire script runs as side-effect on load, cannot be partially imported or deferred. UglifyJS v3 dependency: compress script uses uglify-js directly; Node.js 6+ required to rebuild.

Architecture

Concepts to learn

• REM (Root EM) unit and dynamic font-size scaling — The core mechanism: all REM-based layout units scale proportionally when root <html> font-size changes, enabling one-point responsive scaling instead of media queries per breakpoint
• Viewport units (vw, vh) as modern alternative — CSS's native responsive unit directly tied to window dimensions, superior to lib-flexible's JavaScript approach; understanding why this is recommended as replacement is key to the library's positioning
• Device Pixel Ratio (DPR) and retina scaling — High-DPI devices (retina displays) use multiple physical pixels per CSS pixel; lib-flexible likely detects this via devicePixelRatio to adjust sizing, critical for sharp rendering on modern phones
• FOUC (Flash of Unstyled Content) — If lib-flexible loads asynchronously or after stylesheets, REM values may render at wrong size before recalculation; inlining in <head> prevents this timing bug
• Viewport meta tag configuration — The README mandates a specific viewport meta configuration (width=device-width, initial-scale=1, no zoom); lib-flexible depends on these constraints to calculate correct REM values
• User Agent string parsing for device detection — lib-flexible reads navigator.userAgent to detect device type and apply OS-specific scaling adjustments; critical for Android/iOS layout differences but fragile and maintenance-heavy

Related repos

• vant-contrib/vant-use — Modern hook-based library for Vant (also Alibaba mobile UI) that includes useWindowSize and rem utilities as Vue 3 composables, offering a replacement pattern for lib-flexible in modern SPA stacks
• postcss/postcss-adaptive — Official companion tool recommended in lib-flexible README that transpiles px CSS to rem/vw automatically, required workflow for developers using this library in production

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 automated minification and release

The repo currently has a manual 'compress' script using uglify-js, but no CI/CD pipeline to automate minification on commits or releases. This creates friction for maintainers and risks outdated index.min.js. Adding a GitHub Action would ensure index.min.js stays synchronized with index.js and automate the build-on-release workflow.

• [ ] Create .github/workflows/build.yml that runs 'npm run compress' on push to main
• [ ] Add a step to verify index.min.js changes and optionally commit them back
• [ ] Create .github/workflows/release.yml to generate minified assets when publishing npm releases
• [ ] Update README.md with a 'Contributing' section explaining the automated build process

Add comprehensive unit tests for index.js with test coverage reporting

The repo lacks any test files to validate the core flexible layout logic in index.js. Given this is a mission-critical mobile layout library, unit tests would catch regressions, verify REM calculation across viewport sizes, and provide confidence for contributions. No test directory or framework currently exists.

• [ ] Add devDependency: Jest or Mocha + Chai to package.json
• [ ] Create test/ directory with index.test.js covering viewport calculations, REM conversions, and edge cases
• [ ] Test key scenarios: device width variations, DPI detection, initial vs. resize events
• [ ] Add npm script 'test' to package.json and integrate coverage reporting (e.g., nyc/istanbul)

Create TypeScript declarations (index.d.ts) for better IDE support and type safety

The library exposes a global flexible object but has no TypeScript definitions, limiting adoption by TypeScript projects and IDE autocomplete. A simple index.d.ts would document the API surface (methods, properties) and help users understand what the library does without reading minified code.

• [ ] Create index.d.ts declaring the global 'flexible' object and its public methods/properties
• [ ] Document key exported functions (e.g., 'flexible.init()', viewport calculations) with JSDoc comments
• [ ] Add 'types' field to package.json pointing to index.d.ts for npm consumers
• [ ] Update README.md with a 'TypeScript Support' section showing usage examples

Good first issues

• Add a test suite (currently missing): write Jest tests for the REM calculation function testing viewport widths 320–1920px against expected font-size outputs, ensuring regression prevention for any future scaling logic changes.
• Document the postcss-adaptive integration workflow: create a tutorial in README.md explaining how to configure postcss-adaptive to convert design px files to rem units that work with lib-flexible, with a working example project link.
• Add TypeScript definitions (index.d.ts): create a minimal .d.ts file documenting the library's public API (if any exported functions exist) and type-safe initialization for bundler users, even if the implementation stays vanilla JS.

Top contributors

• @mingelz — 5 commits
• @airen — 2 commits

Recent commits

• 583b9cd — Update README.md (airen)
• 0261549 — Update README.md (airen)
• c483936 — Update: add classic edition link (mingelz)
• a843080 — Update: adjust body font size (mingelz)
• b8f081e — 2.1.0 (mingelz)
• 747d651 — Update: provide compressed file (mingelz)
• 09b2ca6 — New: 2.0 (mingelz)

Security observations

The amfe-flexible library has moderate security concerns primarily related to outdated dependencies and its deprecated status. The primary risk is the outdated uglify-js devDependency (v3.0.27 from 2017) which may contain known vulnerabilities. More critically, the library itself is officially deprecated by maintainers in favor of native viewport units, creating a long-term maintenance and compatibility risk. The codebase is relatively simple with no direct injection vulnerabilities apparent, but lacks security documentation and vulnerability reporting policies. Users are strongly advised to migrate away from this library as recommended in the README.

• High · Outdated UglifyJS DevDependency — package.json - devDependencies. The project uses uglify-js version ^3.0.27, which is significantly outdated (released in 2017). This version may contain known security vulnerabilities and bugs. Modern versions have important security patches and improvements. Fix: Update uglify-js to the latest stable version. Consider using modern alternatives like terser (^5.x) which is actively maintained and has better ES6+ support.
• Medium · No Security Headers or CSP Configuration — README.md, index.js. The library is a script that manipulates viewport and REM calculations. There is no documentation on Content Security Policy (CSP) compatibility or security headers guidance for implementations using this library. Fix: Document CSP compatibility requirements and provide guidance for integrators on proper security headers, especially 'script-src' directives if inline scripts are used.
• Medium · Deprecated Library - Maintenance Risk — README.md. The README explicitly states that lib-flexible is a deprecated transition solution that should no longer be used, as viewport units are now widely supported. Continuing to use or rely on this library poses a long-term maintenance and compatibility risk. Fix: Users should migrate to viewport units (vw, vh, vmin, vmax) instead. The library maintainers should consider archiving the repository or adding prominent deprecation notices.
• Low · Missing SPDX License Identifier — package.json. The package.json specifies 'MIT' license but doesn't include the SPDX license identifier format for better automation and scanning. Fix: While minor, adding SPDX identifier helps with automated compliance scanning. Current format is acceptable but consider adding a LICENSE file with full MIT text.
• Low · No Security.md or Vulnerability Reporting Policy — Repository root. The repository lacks a SECURITY.md file with vulnerability disclosure guidelines and security contact information. Fix: Add a SECURITY.md file with instructions for responsibly reporting security vulnerabilities, following GitHub's recommended format.

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.