Skip to content

borghei/Claude-Skills / engineering/senior-frontend

senior-frontend

Verified

Scaffold Next.js 16 or React + Vite 8 apps, generate components with tests and stories, and flag heavy bundle dependencies. Use when starting a React project, adding components or hooks, or reviewing frontend code or performance.

FileKindSize
SKILL.mdskill md12.2 KB
assets/sample-project-flawed/package.jsonmanifest413 B
assets/sample-project-flawed/src/App.tsxother268 B
assets/sample-project-sound/app/page.tsxother131 B
assets/sample-project-sound/next.config.jsscript255 B
assets/sample-project-sound/package.jsonmanifest476 B
assets/templates/component/client.tsx.tmplother297 B
assets/templates/component/hook.ts.tmplother826 B
assets/templates/component/index.ts.tmplother84 B
assets/templates/component/index_hook.ts.tmplother115 B
assets/templates/component/server.tsx.tmplother447 B
assets/templates/component/story.tsx.tmplother601 B
assets/templates/component/test.tsx.tmplother538 B
assets/templates/scaffold/config/eslint.config.mjs.tmplother190 B
assets/templates/scaffold/config/gitignore.tmplother246 B
assets/templates/scaffold/config/next.config.js.tmplother248 B
assets/templates/scaffold/config/postcss.config.js.tmplother151 B
assets/templates/scaffold/config/prettierrc.tmplother106 B
assets/templates/scaffold/config/tailwind.config.ts.tmplother1.3 KB
assets/templates/scaffold/config/tsconfig.json.tmplother572 B
assets/templates/scaffold/config/vite/eslint.config.js.tmplother361 B
assets/templates/scaffold/config/vite/index.html.tmplother303 B
assets/templates/scaffold/config/vite/postcss.config.js.tmplother149 B
assets/templates/scaffold/config/vite/tsconfig.app.json.tmplother649 B
assets/templates/scaffold/config/vite/tsconfig.json.tmplother119 B
assets/templates/scaffold/config/vite/tsconfig.node.json.tmplother557 B
assets/templates/scaffold/config/vite/vite.config.ts.tmplother282 B
assets/templates/scaffold/files/api_client.tsscript2.1 KB
assets/templates/scaffold/files/auth_client.tsscript1.3 KB
assets/templates/scaffold/files/auth_lib.tsscript2.7 KB
assets/templates/scaffold/files/auth_page.tsxother281 B
assets/templates/scaffold/files/auth_proxy.tsscript525 B
assets/templates/scaffold/files/constants.tsscript327 B
assets/templates/scaffold/files/empty.txtmarkdown0 B
assets/templates/scaffold/files/form_field.tsxother1.7 KB
assets/templates/scaffold/files/form_utils.tsscript762 B
assets/templates/scaffold/files/globals_css.cssother856 B
assets/templates/scaffold/files/health_route.tsscript171 B
assets/templates/scaffold/files/home_page.tsxother304 B
assets/templates/scaffold/files/hook_debounce.tsscript357 B
assets/templates/scaffold/files/hook_local_storage.tsscript659 B
assets/templates/scaffold/files/layout_footer.tsxother265 B
assets/templates/scaffold/files/layout_header.tsxother518 B
assets/templates/scaffold/files/layout_sidebar.tsxother287 B
assets/templates/scaffold/files/login_form.tsxother2.2 KB
assets/templates/scaffold/files/query_client.tsscript662 B
assets/templates/scaffold/files/query_provider.tsxother353 B
assets/templates/scaffold/files/react_app.tsxother403 B
assets/templates/scaffold/files/react_main.tsxother236 B
assets/templates/scaffold/files/register_form.tsxother3.2 KB
assets/templates/scaffold/files/require_auth.tsxother821 B
assets/templates/scaffold/files/root_layout.tsxother512 B
assets/templates/scaffold/files/storybook_main_next.tsscript302 B
assets/templates/scaffold/files/storybook_main_react.tsscript231 B
assets/templates/scaffold/files/storybook_preview_next.tsscript264 B
assets/templates/scaffold/files/storybook_preview_react.tsscript261 B
assets/templates/scaffold/files/test_setup.tsscript244 B
assets/templates/scaffold/files/test_utils.tsxother541 B
assets/templates/scaffold/files/types_index.tsscript309 B
assets/templates/scaffold/files/ui_button.tsxother1.4 KB
assets/templates/scaffold/files/ui_card.tsxother984 B
assets/templates/scaffold/files/ui_index.tsscript147 B
assets/templates/scaffold/files/ui_input.tsxother1.1 KB
assets/templates/scaffold/files/utils.tsscript478 B
assets/templates/scaffold/files/vitest_config_next.tsscript438 B
assets/templates/scaffold/files/vitest_config_react.tsscript389 B
assets/templates/scaffold/manifest.jsonconfig12.6 KB
references/bundle_rules.jsonconfig3.4 KB
references/code-patterns.mdmarkdown5.7 KB
references/frontend_best_practices.mdmarkdown19.4 KB
references/nextjs_optimization_guide.mdmarkdown17.3 KB
references/react_patterns.mdmarkdown16.9 KB
references/tooling-guide.mdmarkdown15.1 KB
scripts/bundle_analyzer.pyexecutablescript11.6 KB
scripts/component_generator.pyexecutablescript8.5 KB
scripts/frontend_scaffolder.pyexecutablescript11.0 KB

scripts/bundle_analyzer.py

View on GitHub
#!/usr/bin/env python3
"""
Frontend Bundle Analyzer

Analyzes package.json and project structure for bundle optimization opportunities,
heavy dependencies, and best practice recommendations.

Usage:
    python bundle_analyzer.py . --json
    python bundle_analyzer.py /path/to/project --verbose --format json
    python bundle_analyzer.py /path/to/project --min-score 70   # CI gate

Rule tables live in references/bundle_rules.json.
Exit codes: 0 ok, 1 score below --min-score (only when the flag is given),
2 bad input (missing directory, no valid package.json, unreadable rules).
"""

import argparse
import json
import re
import sys
from pathlib import Path
from typing import Dict, List, Optional, Tuple


RULES_PATH = Path(__file__).resolve().parent.parent / "references" / "bundle_rules.json"

try:
    with open(RULES_PATH, encoding="utf-8") as _f:
        RULES = json.load(_f)
except (OSError, json.JSONDecodeError) as _exc:
    print(f"Error: cannot load rules from {RULES_PATH}: {_exc}", file=sys.stderr)
    sys.exit(2)

# Known heavy packages and their lighter alternatives
HEAVY_PACKAGES: Dict[str, Dict[str, str]] = RULES["heavy_packages"]
# Recommended optimizations by package
PACKAGE_OPTIMIZATIONS: Dict[str, str] = RULES["package_optimizations"]
# Development dependencies that should not be in dependencies
DEV_ONLY_PACKAGES: List[str] = RULES["dev_only_packages"]
STATE_LIBS: List[str] = RULES["state_libs"]
IMPORT_PATTERNS: List[Tuple[str, str]] = [tuple(p) for p in RULES["import_patterns"]]


def load_package_json(project_dir: Path) -> Optional[Dict]:
    """Load and parse package.json."""
    package_path = project_dir / "package.json"
    if not package_path.exists():
        return None

    try:
        with open(package_path) as f:
            return json.load(f)
    except json.JSONDecodeError:
        return None


def analyze_dependencies(package_json: Dict) -> Dict:
    """Analyze dependencies for issues."""
    deps = package_json.get("dependencies", {})
    dev_deps = package_json.get("devDependencies", {})

    issues = []
    warnings = []
    optimizations = []

    # Check for heavy packages
    for pkg, info in HEAVY_PACKAGES.items():
        if pkg in deps:
            issues.append({"package": pkg, "type": "heavy_dependency", "size": info["size"],
                           "alternative": info["alternative"], "reason": info["reason"]})

    # Check for dev dependencies in production
    for pkg in deps.keys():
        for dev_pattern in DEV_ONLY_PACKAGES:
            if dev_pattern in pkg:
                warnings.append({"package": pkg, "type": "dev_in_production",
                                 "message": f"{pkg} should be in devDependencies, not dependencies"})

    # Check for optimization opportunities
    for pkg in deps.keys():
        for opt_pkg, opt_tip in PACKAGE_OPTIMIZATIONS.items():
            if opt_pkg in pkg:
                optimizations.append({"package": pkg, "tip": opt_tip})

    # Check for outdated React patterns
    if "prop-types" in deps and ("typescript" in dev_deps or "@types/react" in dev_deps):
        warnings.append({"package": "prop-types", "type": "redundant",
                         "message": "prop-types is redundant when using TypeScript"})

    # Check for multiple state management libraries
    found_state_libs = [lib for lib in STATE_LIBS if lib in deps]
    if len(found_state_libs) > 1:
        warnings.append({"packages": found_state_libs, "type": "multiple_state_libs",
                         "message": f"Multiple state management libraries found: {', '.join(found_state_libs)}"})

    return {
        "total_dependencies": len(deps),
        "total_dev_dependencies": len(dev_deps),
        "issues": issues,
        "warnings": warnings,
        "optimizations": optimizations
    }


def detect_framework(package_json: Dict) -> str:
    """Return 'next', 'vite' or 'other' from the declared dependencies."""
    declared = {**package_json.get("devDependencies", {}), **package_json.get("dependencies", {})}
    return "next" if "next" in declared else "vite" if "vite" in declared else "other"


def check_nextjs_config(project_dir: Path) -> Dict:
    """Check Next.js configuration for optimizations."""
    config_paths = [project_dir / f"next.config.{ext}" for ext in ("js", "mjs", "ts")]

    for config_path in config_paths:
        if config_path.exists():
            try:
                content = config_path.read_text()
                suggestions = []
                if "images" not in content:
                    suggestions.append("Configure images.remotePatterns for optimized image loading")
                if "optimizePackageImports" not in content:
                    suggestions.append("Add experimental.optimizePackageImports for lucide-react, @heroicons/react")
                if "transpilePackages" not in content and "swc" not in content:
                    suggestions.append("Consider transpilePackages for monorepo packages")

                return {"found": True, "path": str(config_path), "suggestions": suggestions}
            except Exception:
                pass

    return {"found": False,
            "suggestions": ["Create next.config.js with image and bundle optimizations"]}


def analyze_imports(project_dir: Path) -> Dict:
    """Analyze import patterns in source files."""
    issues = []
    src_dirs = [project_dir / "src", project_dir / "app", project_dir / "pages"]

    files_checked = 0
    for src_dir in src_dirs:
        if not src_dir.exists():
            continue

        for ext in ["*.ts", "*.tsx", "*.js", "*.jsx"]:
            for file_path in src_dir.glob(f"**/{ext}"):
                if "node_modules" in str(file_path):
                    continue

                files_checked += 1
                try:
                    content = file_path.read_text()
                    for pattern, message in IMPORT_PATTERNS:
                        if re.search(pattern, content):
                            issues.append({"file": str(file_path.relative_to(project_dir)),
                                           "issue": message})
                except Exception:
                    continue

    return {"files_checked": files_checked, "issues": issues}


def calculate_score(analysis: Dict) -> Tuple[int, str]:
    """Calculate bundle health score."""
    score = 100

    score -= len(analysis["dependencies"]["issues"]) * 10  # heavy dependencies
    # every warning (dev dep in production, redundant prop-types, overlapping state libs) costs 5
    score -= len(analysis["dependencies"]["warnings"]) * 5
    score -= len(analysis.get("imports", {}).get("issues", [])) * 3
    # Missing next.config (Next projects only; other frameworks carry no "nextjs" key)
    if not analysis.get("nextjs", {}).get("found", True):
        score -= 10

    score = max(0, min(100, score))
    grade = next((g for g, floor in (("A", 90), ("B", 80), ("C", 70), ("D", 60)) if score >= floor), "F")

    return score, grade


WARNING_ADVICE = {"dev_in_production": "Move dev-only packages to devDependencies",
                  "redundant": "Remove prop-types; TypeScript already checks props",
                  "multiple_state_libs": "Consolidate on one state management library"}


def recommendations(analysis: Dict) -> List[str]:
    """One line of advice per kind of finding, in report order."""
    deps = analysis["dependencies"]
    recs = ["Replace heavy dependencies with lighter alternatives"] if deps["issues"] else []
    for kind in dict.fromkeys(w["type"] for w in deps["warnings"]):
        recs.append(WARNING_ADVICE.get(kind, kind))
    if analysis.get("imports", {}).get("issues"):
        recs.append("Fix the flagged import patterns")
    if deps["optimizations"]:
        recs.append("Apply import optimizations for tree-shaking")
    return recs


def print_report(analysis: Dict) -> None:
    """Print human-readable report."""
    score, grade = calculate_score(analysis)

    print("=" * 60)
    print("FRONTEND BUNDLE ANALYSIS REPORT")
    print("=" * 60)
    print(f"\nBundle Health Score: {score}/100 ({grade})")
    print(f"Framework: {analysis.get('framework', 'other')}")

    deps = analysis["dependencies"]
    print(f"\nDependencies: {deps['total_dependencies']} production, {deps['total_dev_dependencies']} dev")

    if deps["issues"]:
        print("\n--- HEAVY DEPENDENCIES ---")
        for issue in deps["issues"]:
            print(f"\n  {issue['package']} ({issue['size']})")
            print(f"    Reason: {issue['reason']}")
            print(f"    Alternative: {issue['alternative']}")

    if deps["warnings"]:
        print("\n--- WARNINGS ---")
        for warning in deps["warnings"]:
            if "package" in warning:
                print(f"  - {warning['package']}: {warning['message']}")
            else:
                print(f"  - {warning['message']}")

    if deps["optimizations"]:
        print("\n--- OPTIMIZATION TIPS ---")
        for opt in deps["optimizations"]:
            print(f"  - {opt['package']}: {opt['tip']}")

    if analysis.get("nextjs", {}).get("suggestions"):
        print("\n--- NEXT.JS CONFIG ---")
        for suggestion in analysis["nextjs"]["suggestions"]:
            print(f"  - {suggestion}")

    if analysis.get("imports", {}).get("issues"):
        print("\n--- IMPORT ISSUES ---")
        for issue in analysis["imports"]["issues"][:10]:  # Limit to 10
            print(f"  - {issue['file']}: {issue['issue']}")

    print("\n--- RECOMMENDATIONS ---")
    for i, rec in enumerate(recommendations(analysis), 1):
        print(f"  {i}. {rec}")
    if not (deps["issues"] or deps["warnings"] or analysis.get("imports", {}).get("issues")):
        print("  Bundle is well-optimized!")

    print("\n" + "=" * 60)


def main():
    parser = argparse.ArgumentParser(description="Analyze frontend project for bundle optimization opportunities")
    parser.add_argument("project_dir", nargs="?", default=".",
                        help="Project directory to analyze (default: current directory)")
    parser.add_argument("--format", choices=["text", "json"], default="text",
                        help="Output format (default: text)")
    parser.add_argument("--json", action="store_true", help="Shorthand for --format json")
    parser.add_argument("--min-score", type=int, default=None,
                        help="Exit 1 when the health score is below this value (default: never fail)")
    parser.add_argument("--verbose", "-v", action="store_true",
                        help="Include detailed import analysis")

    args = parser.parse_args()
    project_dir = Path(args.project_dir).resolve()

    if not project_dir.exists():
        print(f"Error: Directory not found: {project_dir}", file=sys.stderr)
        sys.exit(2)

    package_json = load_package_json(project_dir)
    if not package_json:
        print("Error: No valid package.json found", file=sys.stderr)
        sys.exit(2)

    framework = detect_framework(package_json)
    analysis = {"project": str(project_dir), "framework": framework,
                "dependencies": analyze_dependencies(package_json)}
    if framework == "next":  # next.config checks mean nothing to a Vite or other app
        analysis["nextjs"] = check_nextjs_config(project_dir)

    if args.verbose:
        analysis["imports"] = analyze_imports(project_dir)

    analysis["score"], analysis["grade"] = calculate_score(analysis)

    if args.json or args.format == "json":
        print(json.dumps(analysis, indent=2))
    else:
        print_report(analysis)

    if args.min_score is not None and analysis["score"] < args.min_score:
        print(f"Bundle health score {analysis['score']} is below --min-score {args.min_score}",
              file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall