CLAUDE.md

1# 33 JavaScript Concepts - Project Context
2 
3## Overview
4 
5This repository is a curated collection of **33 essential JavaScript concepts** that every JavaScript developer should know. It serves as a comprehensive learning resource and study guide for developers at all levels, from beginners to advanced practitioners.
6 
7The project was recognized by GitHub as one of the **top open source projects of 2018** and has been translated into 40+ languages by the community.
8 
9## Project Purpose
10 
11- Help developers master fundamental and advanced JavaScript concepts
12- Provide curated resources (articles, videos, books) for each concept
13- Serve as a reference guide for interview preparation
14- Foster community contributions through translations and resource additions
15 
16## Repository Structure
17 
18```
1933-js-concepts/
20├── .claude/                 # Claude configuration
21│   ├── CLAUDE.md           # Project context and guidelines
22│   └── skills/             # Custom skills for content creation
23│       ├── write-concept/  # Skill for writing concept documentation
24│       ├── fact-check/     # Skill for verifying technical accuracy
25│       ├── seo-review/     # Skill for SEO audits
26│       ├── test-writer/    # Skill for generating Vitest tests
27│       ├── resource-curator/ # Skill for curating external resources
28│       └── concept-workflow/ # Skill for end-to-end concept creation
29├── .opencode/               # OpenCode configuration
30│   └── skill/              # Custom skills (mirrored from .claude/skills)
31│       ├── write-concept/  # Skill for writing concept documentation
32│       ├── fact-check/     # Skill for verifying technical accuracy
33│       ├── seo-review/     # Skill for SEO audits
34│       ├── test-writer/    # Skill for generating Vitest tests
35│       ├── resource-curator/ # Skill for curating external resources
36│       └── concept-workflow/ # Skill for end-to-end concept creation
37├── docs/                    # Mintlify documentation site
38│   ├── docs.json           # Mintlify configuration
39│   ├── index.mdx           # Homepage
40│   ├── introduction.mdx    # Getting started guide
41│   ├── contributing.mdx    # Contribution guidelines
42│   ├── translations.mdx    # Community translations
43│   └── concepts/           # 33 concept pages
44│       ├── call-stack.mdx
45│       ├── primitive-types.mdx
46│       └── ... (all 33 concepts)
47├── tests/                   # Vitest test suites
48│   └── fundamentals/       # Tests for fundamental concepts (1-6)
49│       ├── call-stack/
50│       ├── primitive-types/
51│       ├── value-reference-types/
52│       ├── type-coercion/
53│       ├── equality-operators/
54│       └── scope-and-closures/
55├── vitest.config.js        # Vitest configuration
56├── README.md               # Main GitHub README
57├── CONTRIBUTING.md         # Guidelines for contributors
58├── CODE_OF_CONDUCT.md      # Community standards
59├── LICENSE                 # MIT License
60├── package.json            # Project metadata
61├── opencode.jsonc          # OpenCode AI assistant configuration
62└── github-image.png        # Project banner image
63```
64 
65## The 31 Concepts (32nd and 33rd coming soon)
66 
67### Fundamentals (1-6)
681. Primitive Types
692. Value Types and Reference Types
703. Type Coercion (Implicit, Explicit, Nominal, Structuring and Duck Typing)
714. Equality Operators (== vs === vs typeof)
725. Scope & Closures
736. Call Stack
74 
75### Functions & Execution (7-8)
767. Event Loop (Message Queue)
778. IIFE, Modules and Namespaces
78 
79### Web Platform (9-10)
809. DOM and Layout Trees
8110. HTTP & Fetch
82 
83### Object-Oriented JS (11-15)
8411. Factories and Classes
8512. this, call, apply and bind
8613. new, Constructor, instanceof and Instances
8714. Prototype Inheritance and Prototype Chain
8815. Object.create and Object.assign
89 
90### Functional Programming (16-19)
9116. map, reduce, filter
9217. Pure Functions, Side Effects, State Mutation and Event Propagation
9318. Higher-Order Functions
9419. Recursion
95 
96### Async JavaScript (20-22)
9720. Collections and Generators
9821. Promises
9922. async/await
100 
101### Advanced Topics (23-31)
10223. JavaScript Engines
10324. Data Structures
10425. Big O Notation (Expensive Operations)
10526. Algorithms
10627. Inheritance, Polymorphism and Code Reuse
10728. Design Patterns
10829. Partial Applications, Currying, Compose and Pipe
10930. Clean Code
110 
111## Content Format
112 
113Each concept page in `/docs/concepts/` follows this structure:
114 
115### 1. Frontmatter
116```mdx
117---
118title: "Concept Name"
119description: "Brief description of the concept"
120---
121```
122 
123### 2. Real-World Analogy
124Start with an engaging analogy that makes the concept relatable. Include ASCII art diagrams when helpful.
125 
126### 3. Info Box (What You'll Learn)
127```mdx
128<Info>
129**What you'll learn in this guide:**
130- Key point 1
131- Key point 2
132- Key point 3
133</Info>
134```
135 
136### 4. Main Content Sections
137- Use clear headings (`##`, `###`) to organize topics
138- Include code examples with explanations
139- Use Mintlify components (`<AccordionGroup>`, `<Steps>`, `<Tabs>`, etc.)
140- Add diagrams and visualizations where helpful
141 
142### 5. Related Concepts
143```mdx
144<CardGroup cols={2}>
145  <Card title="Related Concept" icon="icon-name" href="/concepts/concept-slug">
146    Brief description of how it relates
147  </Card>
148</CardGroup>
149```
150 
151### 6. Reference
152```mdx
153<Card title="Topic — MDN" icon="book" href="https://developer.mozilla.org/...">
154  Official MDN documentation
155</Card>
156```
157 
158### 7. Articles
159Curated blog posts and tutorials using `<CardGroup>` with `icon="newspaper"`.
160 
161### 8. Courses (optional)
162Educational courses using `<Card>` with `icon="graduation-cap"`.
163 
164### 9. Videos
165YouTube tutorials and conference talks using `<CardGroup>` with `icon="video"`.
166 
167## Contributing Guidelines
168 
169### Adding Resources
170- Resources should be high-quality and educational
171- Follow the existing Card format for consistency
172- Include a brief description of what the resource covers
173 
174### Resource Format
175```mdx
176<Card title="Resource Title" icon="newspaper" href="https://...">
177  Brief description of what the reader will learn from this resource.
178</Card>
179```
180 
181## Git Commit Conventions
182 
183This project follows the [Conventional Commits](https://www.conventionalcommits.org/) specification. All commits must adhere to this format for consistency and automated changelog generation.
184 
185### Commit Message Format
186 
187```
188<type>[optional scope]: <description>
189 
190[optional body]
191 
192[optional footer(s)]
193```
194 
195### Commit Types
196 
197| Type | Description |
198|------|-------------|
199| `feat` | New features or content additions (e.g., new resources, new concepts) |
200| `fix` | Bug fixes, broken link corrections, typo fixes |
201| `docs` | Documentation changes (README updates, CONTRIBUTING updates) |
202| `style` | Formatting changes (markdown formatting, whitespace) |
203| `refactor` | Content restructuring without adding new resources |
204| `chore` | Maintenance tasks (config updates, dependency updates) |
205| `ci` | CI/CD configuration changes |
206| `perf` | Performance improvements |
207| `test` | Adding or updating tests |
208| `build` | Build system or external dependency changes |
209| `revert` | Reverting a previous commit |
210 
211### Examples
212 
213```bash
214# Adding a new resource
215feat: add article about closures by John Doe
216 
217# Fixing a broken link
218fix: update broken MDN link in Promises section
219 
220# Documentation update
221docs: update contributing guidelines for translations
222 
223# Maintenance task
224chore: update opencode.json configuration
225 
226# Adding content to existing concept
227feat(closures): add video tutorial by Fun Fun Function
228 
229# Multiple changes in body
230feat: add new resources for async/await
231 
232- Add article by JavaScript Teacher
233- Add video tutorial by Traversy Media
234- Update reference links
235```
236 
237### Rules
238 
2391. **Use lowercase** for the type and description
2402. **No period** at the end of the description
2413. **Use imperative mood** ("add" not "added", "fix" not "fixed")
2424. **Keep the first line under 72 characters**
2435. **Reference issues** in the footer when applicable (e.g., `Closes #123`)
244 
245## MCP Servers Available
246 
247This project has OpenCode configured with:
248 
2491. **Context7** - Documentation search (`use context7` in prompts)
2502. **GitHub** - Repository management (`use github` in prompts)
251 
252## Testing
253 
254This project uses [Vitest](https://vitest.dev/) as the test runner to verify that code examples in the documentation work correctly.
255 
256### Running Tests
257 
258```bash
259# Run all tests once
260npm test
261 
262# Run tests in watch mode (re-runs on file changes)
263npm run test:watch
264 
265# Run tests with coverage report
266npm run test:coverage
267```
268 
269### Test Structure
270 
271Tests are organized by concept category in the `tests/` directory:
272 
273```
274tests/
275├── fundamentals/              # Concepts 1-6
276│   ├── call-stack/
277│   ├── primitive-types/
278│   ├── value-reference-types/
279│   ├── type-coercion/
280│   ├── equality-operators/
281│   └── scope-and-closures/
282├── functions-execution/       # Concepts 7-8
283│   ├── event-loop/
284│   └── iife-modules/
285└── web-platform/              # Concepts 9-10
286    ├── dom/
287    └── http-fetch/
288```
289 
290### Writing Tests for Code Examples
291 
292When adding new code examples to concept documentation, please include corresponding tests:
293 
2941. **File naming**: Create `{concept-name}.test.js` in `tests/{category}/{concept-name}/`
2952. **Use explicit imports**: 
296```javascript
297   import { describe, it, expect } from 'vitest'
298```
2993. **Convert console.log examples to assertions**:
300```javascript
301   // Documentation example:
302   // console.log(typeof "hello") // "string"
303   
304   // Test:
305   it('should return string type', () => {
306     expect(typeof "hello").toBe("string")
307   })
308```
3094. **Test error cases**: Use `expect(() => { ... }).toThrow()` for operations that should throw
3105. **Skip browser-specific examples**: Tests run in Node.js, so skip DOM/window/document examples
3116. **Note strict mode behavior**: Vitest runs in strict mode, so operations that "silently fail" in non-strict mode will throw `TypeError`
312 
313### Current Test Coverage
314 
315| Category | Concept | Tests |
316|----------|---------|-------|
317| Fundamentals | Call Stack | 20 |
318| Fundamentals | Primitive Types | 73 |
319| Fundamentals | Value vs Reference Types | 54 |
320| Fundamentals | Type Coercion | 74 |
321| Fundamentals | Equality Operators | 87 |
322| Fundamentals | Scope and Closures | 46 |
323| Functions & Execution | Event Loop | 56 |
324| Functions & Execution | IIFE & Modules | 61 |
325| Web Platform | DOM | 85 |
326| Web Platform | HTTP & Fetch | 72 |
327| **Total** | | **628** |
328 
329## Documentation Site (Mintlify)
330 
331The project includes a Mintlify documentation site in the `/docs` directory.
332 
333### Local Development
334 
335```bash
336# Using npm script
337npm run docs
338 
339# Or install Mintlify CLI globally
340npm i -g mint
341cd docs
342mint dev
343```
344 
345The site will be available at `http://localhost:3000`.
346 
347### Documentation Structure
348 
349- **Getting Started**: Homepage and introduction
350- **Fundamentals**: Concepts 1-6 (Primitive Types through Call Stack)
351- **Functions & Execution**: Concepts 7-8 (Event Loop through IIFE/Modules)
352- **Web Platform**: Concepts 9-10 (DOM and HTTP & Fetch)
353- **Object-Oriented JS**: Concepts 11-15 (Factories through Object.create/assign)
354- **Functional Programming**: Concepts 16-19 (map/reduce/filter through Recursion)
355- **Async JavaScript**: Concepts 20-22 (Collections/Generators through async/await)
356- **Advanced Topics**: Concepts 23-31 (JavaScript Engines through Clean Code)
357 
358### Adding/Editing Concept Pages
359 
360Each concept page is in `docs/concepts/` and follows this template:
361 
362```mdx
363---
364title: "Concept Name"
365description: "Brief description"
366---
367 
368## Overview
369[Explanation of the concept]
370 
371## Reference
372[MDN or official docs links]
373 
374## Articles
375[Curated articles with CardGroup components]
376 
377## Videos
378[Curated videos with CardGroup components]
379```
380 
381## Important Notes
382 
383- This is primarily a documentation/resource repository, not a code library
384- The main content lives in `README.md` and `/docs` (Mintlify site)
385- Translations are maintained in separate forked repositories
386- Community contributions are welcome and encouraged
387- MIT Licensed
388 
389## Custom Skills
390 
391### write-concept Skill
392 
393Use the `/write-concept` skill when writing or improving concept documentation pages. This skill provides comprehensive guidelines for:
394 
395- **Page Structure**: Exact template for concept pages (frontmatter, opening hook, code examples, sections)
396- **SEO Optimization**: Critical guidelines for ranking in search results
397- **Writing Style**: Voice, tone, and how to make content accessible to beginners
398- **Code Examples**: Best practices for clear, educational code
399- **Quality Checklists**: Verification steps before publishing
400 
401**When to invoke:**
402- Creating a new concept page in `/docs/concepts/`
403- Rewriting or significantly improving an existing concept page
404- Reviewing an existing concept page for quality
405 
406**SEO is Critical:** Each concept page should rank for searches like:
407- "what is [concept] in JavaScript"
408- "how does [concept] work in JavaScript"
409- "[concept] JavaScript explained"
410 
411The skill includes detailed guidance on title optimization (50-60 chars), meta descriptions (150-160 chars), keyword placement, and featured snippet optimization.
412 
413**Location:** `.claude/skills/write-concept/SKILL.md`
414 
415### fact-check Skill
416 
417Use the `/fact-check` skill when verifying the technical accuracy of concept documentation. This skill provides comprehensive methodology for:
418 
419- **Code Verification**: Verify all code examples produce stated outputs, run project tests
420- **MDN/Spec Compliance**: Check claims against official MDN documentation and ECMAScript specification
421- **External Resource Checks**: Verify all links work and descriptions accurately represent content
422- **Misconception Detection**: Common JavaScript misconceptions to watch for (type coercion, async behavior, etc.)
423- **Test Integration**: Instructions for running `npm test` to verify code examples
424- **Report Template**: Structured format for documenting findings with severity levels
425 
426**When to invoke:**
427- Before publishing a new concept page
428- After significant edits to existing pages
429- When reviewing community contributions
430- Periodic accuracy audits of existing content
431 
432**What gets checked:**
433- Every code example for correct output
434- All MDN links for validity (not 404)
435- API descriptions match current MDN documentation
436- External resources (articles, videos) are accessible and accurate
437- Technical claims are correct and properly nuanced
438- No common JavaScript misconceptions stated as fact
439 
440**Location:** `.claude/skills/fact-check/SKILL.md`
441 
442### seo-review Skill
443 
444Use the `/seo-review` skill when auditing concept pages for search engine optimization. This skill provides a focused audit checklist:
445 
446- **27-Point Scoring System**: Systematic audit across 6 categories
447- **Title & Meta Optimization**: Character counts, keyword placement, compelling hooks
448- **Keyword Strategy**: Pre-built keyword clusters for all JavaScript concepts
449- **Featured Snippet Optimization**: Patterns for winning position zero in search results
450- **Internal Linking**: Audit of concept interconnections and anchor text quality
451- **Report Template**: Structured SEO audit report with prioritized fixes
452 
453**When to invoke:**
454- Before publishing a new concept page
455- When optimizing underperforming pages
456- Periodic content audits
457- After major content updates
458 
459**Scoring Categories (30 points total):**
460- Title Tag (4 points)
461- Meta Description (4 points)
462- Keyword Placement (5 points)
463- Content Structure (6 points)
464- Featured Snippets (4 points)
465- Internal Linking (4 points)
466- Technical SEO (3 points) — Single H1, keyword in slug, no orphan pages
467 
468**Score Interpretation:**
469- 90-100% (27-30): Ready to publish
470- 75-89% (23-26): Minor optimizations needed
471- 55-74% (17-22): Several improvements needed
472- Below 55% (<17): Significant work required
473 
474**Location:** `.claude/skills/seo-review/SKILL.md`
475 
476### test-writer Skill
477 
478Use the `/test-writer` skill when generating Vitest tests for code examples in concept documentation. This skill provides comprehensive methodology for:
479 
480- **Code Extraction**: Identify and categorize all code examples (testable, DOM, error, conceptual)
481- **Test Patterns**: 16 patterns for converting different types of code examples to tests
482- **DOM Testing**: Separate file structure with jsdom environment for browser-specific code
483- **Source References**: Line number references linking tests to documentation
484- **Project Conventions**: File naming, describe block organization, assertion patterns
485- **Report Template**: Test coverage report documenting what was tested and skipped
486 
487**When to invoke:**
488- After writing a new concept page
489- When adding new code examples to existing pages
490- When updating existing code examples
491- To verify documentation accuracy through automated tests
492 
493**Test Categories:**
494- Basic value assertions (`console.log` → `expect`)
495- Error testing (`toThrow` patterns)
496- Async testing (Promises, async/await)
497- DOM testing (jsdom environment, events)
498- Floating point (toBeCloseTo)
499- Object/Array comparisons (toEqual)
500 
501**File Structure:**
502```
503tests/{category}/{concept-name}/{concept-name}.test.js
504tests/{category}/{concept-name}/{concept-name}.dom.test.js  (if DOM examples)
505```
506 
507**Location:** `.claude/skills/test-writer/SKILL.md`
508 
509### resource-curator Skill
510 
511Use the `/resource-curator` skill when finding, evaluating, or maintaining external resources (articles, videos, courses) for concept pages. This skill provides:
512 
513- **Audit Process**: Check existing links for accessibility, accuracy, and relevance
514- **Trusted Sources**: Prioritized lists of reputable article, video, and course sources
515- **Quality Criteria**: Must-have, should-have, and red flag checklists
516- **Description Writing**: Formula and examples for specific, valuable descriptions
517- **Publication Guidelines**: Date thresholds for different topic categories
518- **Report Template**: Audit report for documenting broken, outdated, and missing resources
519 
520**When to invoke:**
521- Adding resources to a new concept page
522- Refreshing resources on existing pages
523- Auditing for broken or outdated links
524- Reviewing community-contributed resources
525- Periodic link maintenance
526 
527**Resource Targets:**
528- Reference: 2-4 MDN links
529- Articles: 4-6 quality articles
530- Videos: 3-4 quality videos
531- Courses: 1-3 (optional)
532 
533**Trusted Sources Include:**
534- Articles: javascript.info, MDN Guides, freeCodeCamp, 2ality, CSS-Tricks, dev.to
535- Videos: Fireship, Web Dev Simplified, Fun Fun Function, Traversy Media, JSConf
536- Courses: javascript.info, Piccalilli, freeCodeCamp, Frontend Masters
537 
538**Location:** `.claude/skills/resource-curator/SKILL.md`
539 
540### concept-workflow Skill
541 
542Use the `/concept-workflow` skill for end-to-end creation of a complete concept page. This orchestrator skill coordinates all five specialized skills in optimal order:
543 
544```
545Phase 1: resource-curator  →  Find quality external resources
546Phase 2: write-concept     →  Write the documentation page
547Phase 3: test-writer       →  Generate tests for code examples
548Phase 4: fact-check        →  Verify technical accuracy
549Phase 5: seo-review        →  Optimize for search visibility
550```
551 
552**When to invoke:**
553- Creating a brand new concept page from scratch
554- Completely rewriting an existing concept page
555- When you want the full end-to-end workflow with all quality checks
556 
557**What it orchestrates:**
558- Resource curation (2-4 MDN refs, 4-6 articles, 3-4 videos)
559- Complete concept page writing (1,500+ words)
560- Comprehensive test generation for all code examples
561- Technical accuracy verification with test execution
562- SEO audit targeting 90%+ score (24+/27)
563 
564**Deliverables:**
565- `/docs/concepts/{concept-name}.mdx` — Complete documentation page
566- `/tests/{category}/{concept-name}/{concept-name}.test.js` — Test file
567- Updated `docs.json` navigation (if new concept)
568- Fact-check report
569- SEO audit report (score 24+/27)
570 
571**Estimated Time:** 2-5 hours depending on concept complexity
572 
573**Example prompt:**
574> "Create a complete concept page for 'hoisting' using the concept-workflow skill"
575 
576**Location:** `.claude/skills/concept-workflow/SKILL.md`
577 
578## Maintainer
579 
580**Leonardo Maldonado** - [@leonardomso](https://github.com/leonardomso)
581 
582## Links
583 
584- Repository: https://github.com/leonardomso/33-js-concepts
585- Issues: https://github.com/leonardomso/33-js-concepts/issues
586- Original Article: [33 Fundamentals Every JavaScript Developer Should Know](https://medium.com/@stephenthecurt/33-fundamentals-every-javascript-developer-should-know-13dd720a90d1) by Stephen Curtis
587