javascript-modern

name	javascript-modern
description	Use when writing or reviewing modern JavaScript for browser or PHP-backed SaaS applications, including modules, asynchronous flows, error handling, language features, and performance.
metadata	{"portable":true,"compatible_with":["claude-code","codex"]}

javascript-modern

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, [phone].

Use When

• Modern JavaScript (ES6+) patterns for PHP+JavaScript SaaS apps: modules, async/await, destructuring, Proxy/Reflect, generators, WeakMap/WeakSet, optional chaining, error handling, and performance patterns. Use when writing JavaScript for web...

Workflow

• For OOP-heavy browser modules, reusable UI widgets, or complex stateful workflows, pair with references/javascript-patterns.md and load references/javascript-patterns.md.
• For Node/runtime container work, pair with docker-development.

Evidence Produced

Category	Artifact	Format	Example
Correctness	JavaScript module test plan	Markdown doc covering async, generators, Proxy, and module boundary tests	docs/web/js-module-tests.md

References

• Use the references/ directory for deep detail after reading the core workflow below.
• Use references/javascript-advanced.md when the task needs deeper ES language mechanics, async patterns, metaprogramming, or performance.
• Use references/javascript-patterns.md when the task involves OOP, prototypes, design patterns, event modules, or maintainable browser architecture.

Expert-level ES6+ patterns for PHP+JavaScript SaaS developers. Assumes fluency with variables, loops, and functions.

Architecture Rule (Non-Negotiable)

JavaScript belongs in its own .js files. PHP only emits a <script src="..."> tag or passes config via a single JSON data attribute. No <?php echo $var ?> scattered through JS files.

<!-- PHP emits one data attribute — no inline JS -->
<div id="app-config"
     data-config='<?= json_encode($config, JSON_HEX_APOS) ?>'
     data-user='<?= json_encode(['id' => $user->id, 'role' => $user->role]) ?>'>
</div>

// assets/js/app.js — reads config cleanly from its own file
const config = JSON.parse(document.getElementById('app-config').dataset.config);
const user   = JSON.parse(document.getElementById('app-config').dataset.user);

---

1. Module Pattern (IIFE + ES Modules)

// assets/js/modules/user-table.js
const UserTable = (() => {
    let tableInstance = null;           // private — unreachable from outside

    function init(config) { tableInstance = new DataTable('#users-table', config); }
    function refresh()    { tableInstance?.ajax.reload(); }

    return { init, refresh };           // public API only
})();

export default UserTable;

// Named exports for shared utilities: assets/js/core/utils.js
export function debounce(fn, delay) { /* ... */ }
export function throttle(fn, limit) { /* ... */ }

---

Additional Guidance

Extended guidance for javascript-modern was moved to references/skill-deep-dive.md to keep this entrypoint compact and fast to load.

Use that deep dive for:

• 2. Async/Await — The Right Patterns
• 3. Production-Grade Fetch Wrapper
• 4. Destructuring — Beyond the Basics
• 5. Optional Chaining and Nullish Coalescing
• 6. Generators for Pagination / Lazy Data
• 7. WeakMap for Private Data and DOM Metadata
• 8. Proxy for Validation and Reactivity
• 9. Error Handling Strategy
• 10. Event Delegation (Performance Pattern)
• 11. Debounce and Throttle
• 12. LocalStorage with Expiry
• 13. const/letand Arrow Functionthis``
• Additional deep-dive sections continue in the reference file.

Decision Rules

Condition	Action
Code is shared across features	Use explicit ES modules with narrow exports
Work is CPU-bound	Move it off the main thread or backend
Legacy IIFE is stable and isolated	Preserve it unless tested conversion adds value

Capability Contract

Read and search are required. Editing and browser or test execution require authorisation; network access is optional.

Degraded Mode

Fallback: without execution, provide a patch plus exact lint, unit, and browser checks still required.

Domain Anti-Patterns

• Starting asynchronous work without handling rejection.
• Using global mutable state instead of module scope.
• Adding a dependency for a native language operation.
• Blocking the main thread with large synchronous transforms.
• Changing module format without checking runtime compatibility.

Inputs

Artefact	Required?	Purpose
JavaScript target, runtime, code, and project conventions	yes	Select compatible language and module patterns

Outputs

• Produce reviewed JavaScript, findings, tests, and compatibility notes.