# 33 JS Concepts Administrator & Developer Guide

This guide is for the people who **maintain, fork, deploy, translate, or extend** the 33-js-concepts repository — not for readers of the curriculum. If you are looking to learn from the curriculum, see the User Guide.

The repository is a deceptively simple thing: 33 canonical concept pages, 29 "Beyond" extension pages, four getting-started pages, around 60 Vitest specs, a Mintlify-built documentation site, and a `package.json` that ties them together. There is no service to run, no database to back up, no API key to rotate, no production traffic to serve. The entire surface area is **static content plus a test runner plus a static-site generator**. That makes the operational concerns quite different from a typical software project — and that is what this guide focuses on.

---

## 1. Architecture Overview

`leonardomso/33-js-concepts` is a **content + executable specs + static documentation site** repository. There is no application binary, no long-running service. The repository's deliverables are:

1. **The README** at the repository root — a curated index of the 33 concepts and outbound links.
2. **MDX concept pages** under `docs/concepts/` (33 files) and `docs/beyond/concepts/` (29 files).
3. **A getting-started track** under `docs/getting-started/` (`about.mdx`, `how-to-learn.mdx`, `learning-paths.mdx`, `prerequisites.mdx`).
4. **A Vitest test suite** under `tests/` mirroring the concept slugs — around 60 spec files including `.test.js` (Node) and `.dom.test.js` (jsdom) variants.
5. **A Mintlify-built documentation site** that consumes `docs/` and renders to a public URL.

### Component inventory

| Component | Path | Role |
|---|---|---|
| Concept pages (canonical 33) | `docs/concepts/*.mdx` | Authoritative explainer per concept. Mintlify-rendered. |
| Concept pages (Beyond 29) | `docs/beyond/concepts/*.mdx` | Advanced extension topics. |
| Getting started pages | `docs/getting-started/*.mdx` | Onboarding: about, how to learn, learning paths, prerequisites. |
| Beyond getting-started | `docs/beyond/getting-started/overview.mdx` | Onboarding for the Beyond track. |
| Top-level index | `docs/index.mdx` | Mintlify home page. |
| Translations index | `docs/translations.mdx` | List of language translations. |
| Contributing index | `docs/contributing.mdx` | Contribution flow as rendered on the docs site. |
| Mintlify config | `docs/docs.json` | Site navigation, theme, metadata. |
| SEO/structured data | `docs/schema-inject.js` | Client-side JSON-LD injector emitting `WebSite`, `TechArticle`, `BreadcrumbList`, `FAQPage`, `ItemList`. |
| Robots directives | `docs/robots.txt` | Crawler hints. |
| Vitest config | `vitest.config.js` | `include: tests/**/*.test.js`, `globals: false`, `environment: 'node'`. |
| Test specs | `tests/<theme>/<slug>/<slug>.test.js` (and `.dom.test.js`) | Executable spec mirroring each concept. |
| Test entry point | `index.js` | Comment-only file documenting the project's intent. |
| Package metadata | `package.json` | Scripts, dev dependencies, keywords. |
| Lockfile | `package-lock.json` | Reproducible installs. |
| OpenCode config | `opencode.jsonc` | Editor/agent integration. |
| Translations charter | `TRANSLATIONS.md` | Process and standards for new translations. |
| Contribution charter | `CONTRIBUTING.md` | Contribution flow, standards, scope. |
| Code of conduct | `CODE_OF_CONDUCT.md` | Contributor Covenant. |
| Licence | `LICENSE` | MIT. |
| Open Graph image | `github-image.png`, `docs/og-image.png` | Social-card branding. |

> [!NOTE]
> The architecture is intentionally minimal. There are no build steps for the concept content — the `.mdx` files are read by Mintlify at site-build time. The only build step in the repository is `vitest run` (for tests) and `mintlify build` (for the docs site). Treat additions to the architecture with extreme scepticism: most "improvements" trade simplicity for marginal gain.

### Architecture diagram

```text
┌────────────────────────────────────────────────────────────────────┐
│                  leonardomso/33-js-concepts repo                    │
├────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  README.md ─────────► outbound-link curated index (the original)    │
│                                                                     │
│  docs/                                                              │
│  ├── index.mdx ─────────► Mintlify home page                        │
│  ├── docs.json ─────────► Mintlify navigation + theme               │
│  ├── schema-inject.js ──► JSON-LD structured data (client-side)     │
│  ├── getting-started/    [4 pages]                                  │
│  ├── concepts/           [33 canonical pages]  ◄──────┐             │
│  └── beyond/                                          │             │
│      ├── getting-started/[1 page]                     │             │
│      └── concepts/        [29 Beyond pages]   ◄────┐  │             │
│                                                    │  │             │
│  tests/                                            │  │             │
│  ├── fundamentals/        [7 specs]    ───────────►┼──┘             │
│  ├── functions-execution/ [5 specs]    ───────────►┘                │
│  ├── functional-programming/ [5 specs] ───────────►(matches concepts)
│  ├── object-oriented/     [4 specs]                                 │
│  ├── advanced-topics/     [7 specs]                                 │
│  ├── async-javascript/    [callbacks]                               │
│  ├── web-platform/        [dom, http-fetch]                         │
│  └── beyond/              [29 specs across sub-themes]              │
│                                                                     │
│  vitest.config.js ──────► test runner config (Node default,         │
│                            jsdom for *.dom.test.js files)           │
│                                                                     │
│  package.json ──────────► npm scripts: test, test:watch,            │
│                            test:coverage, docs, docs:build          │
└────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
                ┌─────────────────────────────────┐
                │    Mintlify-built static site    │
                │  (docs.json drives navigation)   │
                └─────────────────────────────────┘
                                │
                                ▼
                ┌─────────────────────────────────┐
                │   Public documentation URL       │
                │    (Mintlify-hosted or self-     │
                │     hosted on a CDN)              │
                └─────────────────────────────────┘
```

### Technology stack

| Layer | Technology | Pinned version |
|---|---|---|
| Test runner | Vitest | `^4.0.16` |
| Test coverage | `@vitest/coverage-v8` | `^4.0.16` |
| DOM emulation | jsdom | `^27.4.0` |
| Documentation site generator | Mintlify | Invoked via `npx mintlify` (CLI is not pinned in `package.json`) |
| Content format | MDX | Markdown + JSX |
| Source language | Modern JavaScript (ES Modules) | Node 18+ |
| Licence | MIT | — |

### Data flow — typical contributor session

```text
Contributor edits docs/concepts/<slug>.mdx
  └─► npm run docs (local Mintlify dev) ─► localhost:3000 preview
  └─► npm test (Vitest) verifies the matching tests/<theme>/<slug>/<slug>.test.js
  └─► git commit + push + open PR
  └─► Maintainer reviews
  └─► Merge to main
  └─► Mintlify rebuilds and republishes the public site
```

There is no separate "deploy pipeline" beyond the Mintlify rebuild — content changes propagate to readers as soon as the maintainer merges.

> [!NOTE]
> Because the site is read-only and statically generated, there is no traffic spike that would require horizontal scaling. CDN caching at the Mintlify host handles all observable load.

---

## 2. System Requirements

The repository targets two contributor workflows: running the test suite, and running the documentation site. Both are local-only. No production server, no database, no message queue, no Redis.

### Contributor workstation

| Requirement | Minimum | Notes |
|---|---|---|
| Node.js | 18 LTS | Vitest 4 requires Node 18+. The latest LTS is recommended. |
| npm | Bundled with Node | Any package manager works — `npm`, `pnpm`, `yarn`, `bun`. |
| Disk space | ~250 MB | `node_modules` after `npm install`, dominated by Vitest, esbuild binaries, and jsdom. |
| RAM | 2 GB | Vitest uses parallel workers; comfortable with 4 GB. |
| Network | Outbound to `registry.npmjs.org` | Required for `npm install` and for `npx mintlify` first-run download. |
| Editor | Any | VS Code, JetBrains, Vim, Sublime — all work. MDX-aware editing is nice-to-have. |
| Git | 2.x | Standard contribution flow (fork, branch, PR). |

### Operating system support

The repository is OS-neutral. Linux, macOS, and Windows all work. Continuous integration may run on Ubuntu by default but no test relies on Linux-only features.

> [!NOTE]
> The Vitest test suite is split between `*.test.js` files (Node-environment, no DOM) and `*.dom.test.js` files (jsdom-environment). The convention is enforced by Vitest's per-file environment override. There is no Windows-vs-Unix path handling in the suite — all imports use forward slashes.

### Hosting / publishing requirements

If you fork the repository and publish your own site:

| Requirement | Detail |
|---|---|
| Mintlify account (managed) | Easiest path. Connect the GitHub fork; Mintlify rebuilds on push. |
| Static host (self-managed) | `npm run docs:build` produces a static bundle that any static host (Netlify, Vercel, Cloudflare Pages, GitHub Pages, S3+CloudFront) can serve. |
| Custom domain | Configure a `CNAME` or `ALIAS` to your host of choice. |
| HTTPS | Required for the JSON-LD structured-data injector to function correctly when rendered via `https://` canonical URLs. Most static hosts terminate TLS for free. |

---

## 3. Configuration Reference

This is a small project, but every config file matters. Below is the complete set, with every meaningful key documented.

### `package.json`

| Field | Value | Purpose |
|---|---|---|
| `name` | `33-js-concepts` | npm package name (project is not actually published to npm — name is for local use). |
| `version` | `1.0.0` | Static. Bumping is optional. |
| `description` | "A curated collection of 33 essential JavaScript concepts every developer should master…" | Repository tagline; used in npm metadata. |
| `main` | `index.js` | Entry point declaration. The file itself is comment-only. |
| `author.name` | `Leonardo Maldonado` | Original author. |
| `author.url` | `https://github.com/leonardomso` | Author's GitHub. |
| `license` | `MIT` | Licence. |
| `bugs.url` | `https://github.com/leonardomso/33-js-concepts/issues` | Issue tracker. |
| `homepage` | `https://github.com/leonardomso/33-js-concepts#readme` | Project home. |
| `repository.type` | `git` | — |
| `repository.url` | `git+https://github.com/leonardomso/33-js-concepts.git` | — |
| `scripts.test` | `vitest run` | Run the entire test suite once. |
| `scripts.test:watch` | `vitest` | Watch mode — re-run on file save. |
| `scripts.test:coverage` | `vitest run --coverage` | Run with coverage instrumentation (`@vitest/coverage-v8`). |
| `scripts.docs` | `cd docs && npx mintlify dev` | Start a local docs server. |
| `scripts.docs:build` | `cd docs && npx mintlify build` | Produce a production docs build. |
| `keywords` | 27 keywords incl. `javascript`, `closures`, `promises`, `async-await`, `event-loop`, `prototypes`, `interview-preparation` | Used in npm and search ranking. |
| `devDependencies.@vitest/coverage-v8` | `^4.0.16` | V8 coverage. |
| `devDependencies.jsdom` | `^27.4.0` | DOM emulation for `*.dom.test.js`. |
| `devDependencies.vitest` | `^4.0.16` | Test runner. |

> [!IMPORTANT]
> No `dependencies` (production) are declared. The repository ships **zero** runtime code, so there is nothing to depend on. If a future PR proposes adding a runtime dependency, scrutinise the rationale — most plausible additions belong in `devDependencies`.

### `vitest.config.js`

```javascript
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    include: ['tests/**/*.test.js'],
    globals: false,
    environment: 'node'
  }
})
```

| Key | Value | Effect |
|---|---|---|
| `test.include` | `['tests/**/*.test.js']` | Globs that select files. The pattern matches both `<concept>.test.js` and `<concept>.dom.test.js`. |
| `test.globals` | `false` | Test files must `import { describe, it, expect } from 'vitest'`. Prevents accidental reliance on global APIs. |
| `test.environment` | `'node'` | Default environment. Files ending in `.dom.test.js` get jsdom via Vitest's per-file inference. |

> [!IMPORTANT]
> Do not change `globals: false` to `true` without updating every test file. The project's deliberate stance is that imports are explicit — this makes the test files readable as standalone study material.

### `docs/docs.json`

The Mintlify configuration file. It declares site navigation (sidebar groups, page order), theme tokens (colours, fonts), site metadata (title, description, social links), and search behaviour. Edit this file when you add a new concept page so it appears in the rendered navigation.

### `docs/schema-inject.js`

A self-contained IIFE that injects JSON-LD structured data into every page on the rendered site. Behaviour:

| Page type | Emitted Schema.org payload |
|---|---|
| Home page (`/`) | `WebSite` (with `SearchAction`), and an `ItemList` of up to 33 concept links derived from on-page anchors. |
| Concept article (`/concepts/<slug>` or `/beyond/concepts/<slug>`) | `TechArticle` + `BreadcrumbList`. If a "Frequently Asked Questions" `<h2>` exists, also a `FAQPage`. |
| Other pages | `WebPage` + `BreadcrumbList`. |

Constants you may want to override in a fork:

```javascript
var SITE_NAME = "33 JavaScript Concepts";
var SCHEMA_SCRIPT_ID = "structured-data-jsonld";
var AUTHOR = {
  "@type": "Person",
  name: "Leonardo Maldonado",
  url: "https://github.com/leonardomso",
};
var PUBLISHER = {
  "@type": "Organization",
  name: SITE_NAME,
};
```

> [!NOTE]
> The injector runs on `DOMContentLoaded` (or immediately if the DOM is already ready). It is idempotent — repeated calls to `injectSchema()` overwrite the same `<script id="structured-data-jsonld">` element rather than appending duplicates.

### `docs/robots.txt`

Standard search-engine directives. Edit if you fork and want to change indexing behaviour.

### `opencode.jsonc`

Project-level configuration for the `opencode` editor/agent tooling. Optional — has no effect on tests, docs, or content.

### Environment variables

The project does not read any environment variables at test or build time. There is no `.env` to set up.

---

## 4. Deployment & Scaling

The repository is deployed as a **static documentation site** plus a **GitHub-hosted source-of-truth**. Operational simplicity is the headline feature.

### Deployment surface

| Asset | Where it lives | Refresh trigger |
|---|---|---|
| GitHub repository | `github.com/leonardomso/33-js-concepts` | Push to `main`. |
| Documentation site | Mintlify-hosted (managed) — or any static host you point at `docs:build` output | Push to `main` (Mintlify-managed) or manual rebuild (self-hosted). |
| npm package | Not published. | — |
| Docker image | Not published. | — |
| GitHub Pages | Optional. Build via `npm run docs:build` and copy the output to a `gh-pages` branch. | — |

### Mintlify-managed deployment (recommended)

1. Connect the repository to Mintlify via Mintlify's GitHub integration.
2. Mintlify rebuilds the site on every push to `main`.
3. Configure your custom domain in Mintlify's dashboard.
4. The `docs/docs.json` file controls the site's structure; commits to that file propagate within minutes of merge.

### Self-managed static deployment

```bash
# In repository root
npm install
cd docs
npx mintlify build
```

The build emits a static bundle. Upload the bundle to any static host:

| Host | Notes |
|---|---|
| GitHub Pages | Push the build to a `gh-pages` branch. Use a `CNAME` file for a custom domain. |
| Netlify | Connect the repo and set `npm run docs:build` as the build command, output directory as Mintlify's default. |
| Vercel | Connect the repo. Build command `npm run docs:build`. |
| Cloudflare Pages | Same pattern as Vercel. Cloudflare's edge cache is excellent for read-heavy static content. |
| S3 + CloudFront | Sync the build output to an S3 bucket; serve via CloudFront with HTTPS. |

> [!TIP]
> Pre-warm the CDN after each rebuild by hitting at least the home page and a representative concept page. Mintlify-managed deployment handles this for you.

### Scaling

Reads scale linearly with the static host's CDN. There is no write side, no database, no rate limit to tune. A traffic spike of 10x or 100x is invisible to the repository — only to the CDN bill.

### Continuous integration

The project does not currently ship a CI configuration in the briefing's `.github/workflows` listing. A typical CI for this repo would:

1. Run `npm install`.
2. Run `npm test` (Vitest).
3. Run `npm run docs:build` (Mintlify) to verify the docs site builds without errors.
4. Optionally run a link checker (`lychee`, `markdown-link-check`) against `docs/` to catch decayed outbound links.

> [!NOTE]
> If you are setting up CI for a fork, gate `merge to main` on (a) all tests green and (b) docs build green. Outbound-link health checks should report-only (warn, don't fail) — the project links to many third-party sites that occasionally throttle automated checkers.

---

## 5. Operations

### Runbook — adding a concept to the canonical 33

Adding a new concept to the canonical 33 is a substantial commitment. The list has been deliberately stable. If a concept genuinely deserves inclusion:

- [ ] Open an issue describing the concept, why it deserves canonical status, and which (if any) existing concept it replaces.
- [ ] Wait for maintainer alignment before writing code.
- [ ] Create `docs/concepts/<slug>.mdx` mirroring the structure of an existing canonical page.
- [ ] Create `tests/<theme>/<slug>/<slug>.test.js` mirroring the structure of an existing test file. Use `.dom.test.js` if the concept needs the DOM.
- [ ] Update the README's table-of-contents to include the new concept and renumber if needed.
- [ ] Update `docs/docs.json` so the new page appears in the rendered navigation.
- [ ] Update `docs/index.mdx` if it references the count "33".
- [ ] Run `npm test` and `npm run docs:build` locally.
- [ ] Open a PR with a short rationale and link to the issue.

### Runbook — adding a Beyond topic

Adding a Beyond topic is lower-stakes. The Beyond list is intended to grow.

- [ ] Pick a sub-theme (`browser-storage`, `data-handling`, `events`, `language-mechanics`, `memory-performance`, `modern-syntax-operators`, `objects-properties`, `observer-apis`, `type-system`) or open an issue proposing a new sub-theme.
- [ ] Create `docs/beyond/concepts/<slug>.mdx`.
- [ ] Create `tests/beyond/<sub-theme>/<slug>/<slug>.test.js`.
- [ ] Update `docs/docs.json` so the new page appears in the Beyond navigation.
- [ ] Run tests and docs build.
- [ ] Open a PR.

### Runbook — accepting a translation

- [ ] Verify the contributor has read `CONTRIBUTING.md` and `TRANSLATIONS.md`.
- [ ] Verify slugs in the translation match the English originals (so cross-links resolve).
- [ ] Run a basic sanity check on the translated pages — at least one MDX render via `npm run docs`.
- [ ] Update `docs/translations.mdx` and `TRANSLATIONS.md` to list the new language.
- [ ] Merge.

### Runbook — link rot maintenance

Outbound links in `docs/concepts/<slug>.mdx` decay over time. Periodically:

- [ ] Run an automated link checker against `docs/concepts/` and `docs/beyond/concepts/`.
- [ ] For each 404, search the original article title — many authors have migrated to a new domain.
- [ ] Replace dead links with Wayback Machine archives (`https://web.archive.org/web/*/<original-url>`) when no replacement exists.
- [ ] Open a single PR per maintenance run, listing every replaced link in the PR body.

> [!TIP]
> Run link maintenance quarterly. Monthly is overkill; annually is too rare. The project linked to a wide variety of third-party blogs over the years; perhaps 2-5% of links go stale per quarter.

### Backups

Source of truth is GitHub. There is no database. The Mintlify-rendered site is regenerable from source, so the only thing to back up is the Git history — and GitHub provides that.

> [!NOTE]
> If you are running on a self-managed Mintlify deployment, also back up `docs/docs.json` and your custom `docs/schema-inject.js` overrides — they are part of the source repo and travel with it automatically.

### Monitoring

For the published docs site, the operational signals worth watching:

| Signal | Source | Action threshold |
|---|---|---|
| Site uptime | Mintlify status / your CDN's status page | Investigate any sustained outage. |
| 404 rate | CDN access logs | Spike suggests a navigation regression after a recent merge. |
| Link-check report | Periodic `lychee` run | Replace decayed outbound links. |
| Search-engine indexing | Google Search Console / Bing Webmaster | Drop in indexed pages may indicate a `robots.txt` or canonical-URL regression. |
| Build failures | Mintlify build logs / CI | Fail-fast investigation — usually an MDX syntax error. |

---

## 6. Performance

The performance profile is dominated by **read latency** to the rendered docs site. There is no write path, no database query, no API call.

### Static-site performance

Mintlify (and any decent static host) emits HTML, CSS, JavaScript, and images that a CDN can serve in 50-200ms TTFB worldwide. The dominant performance lever is CDN cache hit rate; aim for ≥99%.

### `docs/schema-inject.js` overhead

The structured-data injector runs once per page on `DOMContentLoaded`. It traverses the DOM to extract a heading, breadcrumbs, and (on concept pages) FAQ items — bounded by the page's own DOM size. The work is O(N) in the number of FAQ `<button>` elements and O(M) in the number of `<a>` links on the home page (capped at 33 concepts). On a typical concept page this completes in under 5 ms.

> [!NOTE]
> The injector is **idempotent** — repeated invocations rewrite the same `<script id="structured-data-jsonld">` element rather than appending duplicates. SPAs that re-render via client-side routing should re-invoke `injectSchema()` after each route change; the current implementation does not subscribe to history events, so re-invocation is the host site's responsibility.

### Test suite performance

`npm test` runs ~60 spec files in parallel. Wall-clock time on a modern laptop is typically 5-15 seconds. With coverage enabled (`npm run test:coverage`) expect 2-3x. Vitest's default worker pool sizing is appropriate; do not pin `--threads` unless you have a specific reason.

> [!TIP]
> If `npm test` runs slowly in CI, the most common cause is an under-provisioned runner (1 CPU, 2 GB RAM). Vitest scales well to 4-8 CPUs.

### Documentation site build performance

`npm run docs:build` runs Mintlify's build pipeline, which is dominated by MDX compilation. With ~70 pages, build time is typically 30-90 seconds. This is rarely a bottleneck.

> [!TIP]
> If a PR slows the docs build noticeably, audit the MDX changes — heavy custom JSX components (interactive widgets, embedded React) can blow up build time disproportionately. Keep concept pages mostly prose and code blocks.

### CDN cache strategy

Set aggressive cache headers on built assets (long `max-age`, `immutable` for hashed files) and shorter TTLs on the HTML pages so content updates propagate quickly. Most static hosts handle this automatically with sensible defaults.

---

## 7. Security

This is a **public, read-only, statically generated documentation site** that ships no executable code to readers' machines beyond a minor structured-data injector. The threat surface is correspondingly small.

### Threats in scope

| Threat | Likelihood | Mitigation |
|---|---|---|
| Outbound link decay (404, paywalled, or redirected to spam) | High over multi-year horizon | Periodic link checks (Section 5 runbook). |
| Outbound link redirected to malicious content (domain hijack) | Low but non-zero | Periodic spot-checks of links, especially for low-traffic blogs. Reserve `rel="noopener noreferrer"` on outbound links rendered by Mintlify. |
| MDX injection via PR | Low (PRs are reviewed) | Maintainer review of every PR; no auto-merge. |
| Malicious dev-dependency (supply chain) | Low (3 dev deps, all reputable) | Pinning via `package-lock.json`; periodic `npm audit`. |
| Credential exposure in repo | None known | The repository ships no secrets; `.env` is not used. |
| XSS via `docs/schema-inject.js` | Very low | The script reads DOM content via `safeText()` (whitespace-collapse, trim) and emits JSON-LD via `JSON.stringify` — no `innerHTML` writes. |

> [!WARNING]
> The single most important security practice here is **outbound-link hygiene**. The repository does not own the domains it links to. A blog domain that lapses can be re-registered by a third party and used to serve malware. Periodically spot-check the curated reading lists, especially for older concept pages with many links to long-tail blogs.

### Sensitive material

The repository contains no secrets, no credentials, no private user data, no personally identifiable information beyond the author's public GitHub handle. All content is intended to be public. There is no data classification beyond "all public, MIT-licensed."

> [!CAUTION]
> If you fork this repo to build a commercial offering, **do not** copy contributor email addresses or PR comments without consent. Public PR metadata is technically public, but treating contributors' names and emails as bulk-extractable data invites GDPR exposure if you operate in or serve EU readers.

### `docs/schema-inject.js` review

The injector's read-only DOM traversal uses defensive try/catch around every read and never executes user-supplied strings. It writes only:

1. A single `<script type="application/ld+json">` tag.
2. The `text` property of that tag, set to `JSON.stringify(...)` output (safe — JSON cannot escape into HTML).

There is no eval, no Function constructor, no innerHTML. The script's only side effect is that `<script>` tag, scoped to the rendered docs site.

### Dependency hygiene

Run `npm audit` periodically. The dev dependencies (`vitest`, `@vitest/coverage-v8`, `jsdom`) are well-maintained. Transitive vulnerabilities are common in `node_modules` but rarely affect a project that ships no runtime code — the only blast radius is the contributor's local machine when running tests.

> [!WARNING]
> Do not run `npm install` against a fork's PR branch on a sensitive workstation. Use a sandbox (container, dedicated user) if you ever need to run a third-party fork's install scripts. Standard supply-chain hygiene applies.

### Reporting a security issue

For genuine security concerns (e.g. a contributor PR that injects unsafe MDX, a `schema-inject.js` regression that allows DOM-XSS), open a private security advisory via GitHub. Do not file public issues describing exploitable bugs — coordinate with the maintainer first.

---

## 8. Developer Internals

### Repository structure

```text
33-js-concepts/
├── README.md                  Top-level curated index — the original deliverable.
├── CONTRIBUTING.md            Contribution flow and standards.
├── CODE_OF_CONDUCT.md         Contributor Covenant.
├── TRANSLATIONS.md            Translation process and accepted languages.
├── LICENSE                    MIT.
├── github-image.png           Open-Graph image for GitHub.
├── index.js                   Comment-only entry point — declares project intent.
├── package.json               Scripts and dev dependencies.
├── package-lock.json          Locked dependency tree.
├── vitest.config.js           Test runner configuration.
├── opencode.jsonc             OpenCode tooling configuration.
├── .gitignore                 Standard Node ignores.
│
├── docs/                      Mintlify documentation site source.
│   ├── index.mdx              Site home page.
│   ├── docs.json              Mintlify navigation, theme, metadata.
│   ├── schema-inject.js       JSON-LD structured-data injector.
│   ├── robots.txt             Crawler directives.
│   ├── og-image.png           Social card.
│   ├── favicon.ico            Site favicon.
│   ├── 5c8wamucvfketshf1eyrw254gz94jwre.txt  Domain-verification or static asset (deployment artefact).
│   ├── contributing.mdx       Contribution flow rendered in-site.
│   ├── translations.mdx       Translations index rendered in-site.
│   ├── getting-started/
│   │   ├── about.mdx          What is this curriculum?
│   │   ├── how-to-learn.mdx   Project's recommended approach.
│   │   ├── learning-paths.mdx Suggested orderings (interview prep, fundamentals first, async track, etc.).
│   │   └── prerequisites.mdx  What you should know before starting.
│   ├── concepts/              The canonical 33 concept pages.
│   │   ├── call-stack.mdx
│   │   ├── primitive-types.mdx
│   │   ├── primitives-objects.mdx
│   │   ├── type-coercion.mdx
│   │   ├── equality-operators.mdx
│   │   ├── scope-and-closures.mdx
│   │   ├── javascript-engines.mdx
│   │   ├── event-loop.mdx
│   │   ├── factories-classes.mdx
│   │   ├── this-call-apply-bind.mdx
│   │   ├── object-creation-prototypes.mdx
│   │   ├── inheritance-polymorphism.mdx
│   │   ├── iife-modules.mdx
│   │   ├── es-modules.mdx
│   │   ├── http-fetch.mdx
│   │   ├── callbacks.mdx
│   │   ├── promises.mdx
│   │   ├── async-await.mdx
│   │   ├── higher-order-functions.mdx
│   │   ├── map-reduce-filter.mdx
│   │   ├── pure-functions.mdx
│   │   ├── currying-composition.mdx
│   │   ├── recursion.mdx
│   │   ├── data-structures.mdx
│   │   ├── algorithms-big-o.mdx
│   │   ├── dom.mdx
│   │   ├── design-patterns.mdx
│   │   ├── modern-js-syntax.mdx
│   │   ├── error-handling.mdx
│   │   ├── regular-expressions.mdx
│   │   ├── clean-code.mdx
│   │   ├── generators-iterators.mdx
│   │   └── web-workers.mdx
│   └── beyond/
│       ├── getting-started/overview.mdx
│       └── concepts/          The 29 Beyond pages, grouped by sub-theme in tests/.
│
└── tests/
    ├── fundamentals/          call-stack, equality-operators, javascript-engines, primitive-types, primitives-objects, scope-and-closures, type-coercion
    ├── functions-execution/   async-await, event-loop, generators-iterators, iife-modules, promises
    ├── functional-programming/ currying-composition, higher-order-functions, map-reduce-filter, pure-functions, recursion
    ├── object-oriented/       factories-classes, inheritance-polymorphism, object-creation-prototypes, this-call-apply-bind
    ├── advanced-topics/       algorithms-big-o, data-structures, design-patterns, error-handling, es-modules, modern-js-syntax, regular-expressions
    ├── async-javascript/      callbacks (.test.js + .dom.test.js)
    ├── web-platform/          dom, http-fetch
    └── beyond/
        ├── browser-storage/   cookies (incl. .dom.test.js), indexeddb, localstorage-sessionstorage (incl. .dom.test.js)
        ├── data-handling/     blob-file-api (incl. .dom.test.js), json-deep-dive, requestanimationframe, typed-arrays-arraybuffers
        ├── events/            custom-events (incl. .dom.test.js), event-bubbling-capturing (.dom.test.js), event-delegation
        ├── language-mechanics/ hoisting, strict-mode, temporal-dead-zone
        ├── memory-performance/ debouncing-throttling, garbage-collection, memoization, memory-management
        ├── modern-syntax-operators/ computed-property-names, tagged-template-literals
        ├── objects-properties/ getters-setters, object-methods, property-descriptors, proxy-reflect, weakmap-weakset
        ├── observer-apis/     intersection-observer (incl. .dom.test.js), mutation-observer (.dom.test.js), performance-observer, resize-observer
        └── type-system/       javascript-type-nuances
```

### Adding a new concept (canonical 33 or Beyond)

The canonical procedure mirrors the existing files. **Treat consistency as the highest virtue** — readers expect every concept page to feel structurally identical.

1. **Pick the slug.** Use kebab-case. Match the slug already used in `tests/` if a test exists, or create both at once.
2. **Create the MDX page.** Open a sibling page (e.g. `docs/concepts/scope-and-closures.mdx`) as a template. Copy its frontmatter (Mintlify-specific meta), its section structure (Definition → How it works → Examples → Articles → Videos → Cross-links), and adapt to the new concept.
3. **Create the test file.** Place under `tests/<theme>/<slug>/<slug>.test.js`. If the concept needs the DOM (anything touching `document`, `window`, `localStorage`, cookies, or events), use `<slug>.dom.test.js`. Each test file should `import { describe, it, expect } from 'vitest'` (and any of `vi`, `beforeEach`, `afterEach` it needs) — `globals: false` is the project's convention.
4. **Update `docs/docs.json`.** Add the new page to the appropriate Mintlify navigation group so it appears in the rendered sidebar.
5. **Update the README.** Add a row to the curated index in alphabetical-or-numbered order matching the existing pattern.
6. **Verify locally.** Run `npm test` and `npm run docs` and confirm the new page is reachable from the rendered navigation.

### The translation directory pattern

Translations historically lived at the repository root in `translations/<lang-code>/` (per `TRANSLATIONS.md`). Each translation duplicates the README in the target language. Since the migration to a Mintlify-rendered site, translations may also live as language-prefixed routes (`docs/<lang-code>/`) — check `TRANSLATIONS.md` for the current canonical layout. Either way:

- Slugs **must** match the English originals so cross-links work.
- Image references should use the same paths.
- Code samples should not be translated (variable names, function names) — only prose.

> [!IMPORTANT]
> Translations are accepted on a best-effort basis. The maintainer may not speak the target language and relies on the translator's good faith and on community review. Open a PR even if the translation is incomplete — incremental translations are welcome.

### Coding conventions in test files

Every test file follows the same shape:

```javascript
import { describe, it, expect } from 'vitest'
// optionally: import { vi, beforeEach, afterEach } from 'vitest'

describe('<Concept Name>', () => {

  // ============================================================
  // SECTION HEADERS LIKE THIS GROUP RELATED BEHAVIOURS
  // ============================================================

  describe('<sub-topic>', () => {
    it('should <expected behaviour>', () => {
      // From: short comment quoting the concept page
      // ...assertion...
    })
  })

  // more describe blocks...
})
```

The big-comment-banner section markers (`// ============`) are deliberate — they make the test files browseable as study material, not just executable. When adding a new test file, mirror the banner style of an existing file in the same theme.

### Code patterns and conventions

- **Imports are explicit.** No globals (`globals: false`).
- **Tests read top-to-bottom as a study guide.** Order `describe` blocks from simple to complex.
- **Comments quote the concept page.** Many tests include `// From: <quote>` comments tying the assertion back to the prose. Maintain this — it is the project's anti-fabrication pattern.
- **DOM tests use the `.dom.test.js` suffix.** Vitest's per-file environment override switches them to jsdom.
- **No external mocks.** The tests target language and browser-platform behaviour, not third-party libraries. There are no API mocks, no network shims.

### Testing strategy

| Layer | Strategy |
|---|---|
| Concept correctness | Each concept page has a sibling test file whose assertions exercise the same behaviour. The test file is the executable contract. |
| Cross-concept consistency | Tests are isolated per concept; cross-concept consistency is enforced by review, not by automation. |
| DOM correctness | `.dom.test.js` files run under jsdom. Some browser-only APIs (Performance Observer, Resize Observer) are partially polyfilled by jsdom; tests assert behaviour that jsdom actually implements. |
| Mintlify build | `npm run docs:build` should be part of CI. A failing build is almost always an MDX syntax error. |
| Outbound link health | Out of scope for the test suite; covered by periodic link-check runs (Section 5). |

### Potential improvements

- **CI configuration in the repo.** A `.github/workflows/ci.yml` running `npm test` and `npm run docs:build` on every PR would prevent regressions.
- **Automated link checker.** A scheduled GitHub Action running `lychee` against `docs/concepts/` and `docs/beyond/concepts/` would surface decayed outbound links proactively.
- **Translation health dashboard.** As translations accumulate, a per-language coverage table (which concept pages have been translated, which are stale) would help prioritise contribution effort.
- **Concept-page frontmatter schema.** Lock down the Mintlify frontmatter expected on every concept page (title, description, sidebar position, last-reviewed date) and validate via a small script in CI.
- **Beyond-track stability.** The Beyond directory's sub-theme structure has grown organically. A future cleanup pass could consolidate sub-themes (e.g. merge `modern-syntax-operators` into a broader `syntax` theme) for clearer navigation.

### Contributing guide (for engineers)

The high-level flow:

1. Read `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md`.
2. Open an issue describing your proposed change before sending a large PR.
3. Fork, branch, edit, test, build docs.
4. Open a PR with a clear description and link to the issue.
5. Address review feedback.

Common PR types and expected effort:

| PR type | Typical review depth |
|---|---|
| Typo / grammar fix | Light. Approved within days. |
| Broken-link replacement | Light. Approved within days. |
| New outbound resource on an existing concept | Moderate. Reviewer checks link quality and relevance. |
| New Beyond topic | Moderate-to-heavy. Reviewer expects matching test file and Mintlify navigation update. |
| New canonical 33 entry | Heavy. Requires prior issue alignment. |
| Translation | Light-to-moderate. Reviewer checks slug conformance and high-level structure. |

> [!TIP]
> The fastest way to get a PR merged is to mirror the structure of an existing accepted PR. The repository's PR history is the best reference for "what does a good contribution look like."

---

## 9. Integration Points

### Outbound integrations

| Integration | Purpose | Replaceable? |
|---|---|---|
| Mintlify (docs renderer) | Builds the published documentation site from `docs/`. | Yes — any MDX-aware static site generator (Docusaurus, Astro Starlight, VitePress) could replace it. The migration cost would be configuration (docs.json → equivalent), not content. |
| Vitest (test runner) | Runs the `.test.js` and `.dom.test.js` specs. | Yes — Jest, Mocha, or node:test could run the suite with minimal changes. The `import { describe, it, expect } from 'vitest'` lines would need updating, and the per-file environment auto-detection (`.dom.test.js` → jsdom) would need an equivalent in the new runner. |
| jsdom | Provides a browser-like environment for `.dom.test.js`. | Yes — `happy-dom` is a faster alternative that supports most APIs the project uses. |
| `@vitest/coverage-v8` | Coverage instrumentation when `npm run test:coverage` runs. | Yes — `c8` (V8) or `istanbul` could replace it. |
| GitHub | Source-of-truth hosting, issues, PRs. | Yes in principle (GitLab, Codeberg) — practically, GitHub is where the contributors are. |
| OpenCode | Editor/agent tooling per `opencode.jsonc`. | Optional — has no effect on the published deliverables. |

### Inbound integrations

| Integration | Purpose |
|---|---|
| Search engines (Google, Bing, DuckDuckGo) | Index the published site. The `docs/schema-inject.js` injector emits Schema.org structured data to improve rich-result eligibility (`TechArticle`, `BreadcrumbList`, `FAQPage`, `ItemList`). |
| `https://web.archive.org` (Wayback Machine) | Archives the site over time. Useful as a fallback for decayed outbound links. |
| Curated lists / aggregators | Many "awesome-javascript" lists link to this repository. The README's curated index is the public-facing entry point. |
| Translators | The `TRANSLATIONS.md` flow is the inbound integration for community translations. |

### Public URLs

| URL | Purpose |
|---|---|
| `https://github.com/leonardomso/33-js-concepts` | Source repository. |
| `https://github.com/leonardomso/33-js-concepts/issues` | Issue tracker. |
| The Mintlify-rendered docs site (project's primary public URL) | Published documentation. |

### Schema.org / structured data

The `docs/schema-inject.js` injector emits a JSON-LD `@graph` containing:

| Page type | Top-level types |
|---|---|
| Home | `WebSite` (with `SearchAction`), `ItemList` of up to 33 concepts. |
| Concept article | `TechArticle` (headline, description, URL, author, publisher, datePublished, dateModified) + `BreadcrumbList`. Plus `FAQPage` if a "Frequently Asked Questions" `<h2>` is present on the page. |
| Other pages | `WebPage` + `BreadcrumbList`. |

This is consumed by search engines and AI crawlers to improve indexing and rich-result eligibility. It is not consumed by readers directly.

> [!NOTE]
> The injector runs client-side. Server-rendered structured data (e.g. baked into the static HTML at build time) would be more robust for non-JavaScript crawlers — a future improvement could move the JSON-LD generation into a Mintlify plugin or build-time script.

### Issue references — recent community signals

| Issue | Status | Lesson |
|---|---|---|
| [#481](https://github.com/leonardomso/33-js-concepts/issues/481) | Closed | An early version of the value-types/reference-types content was flagged as misleading. The page has since been revised. The lesson: even canonical pages can have errors; the test-file pairing is the project's anti-regression mechanism. |
| [#544](https://github.com/leonardomso/33-js-concepts/issues/544) | Closed | A request to add a dedicated topic for `this` in functions and objects. The material is now part of `docs/concepts/this-call-apply-bind.mdx`. The lesson: the canonical 33 cover the territory, even if the topic-naming differs from a reader's expectation. |

---

_Generated April 2026 from leonardomso/33-js-concepts at 60f9337. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._