This guide explains how to set up the JavaScript Reference repository, navigate its documentation, run examples, and use the project effectively as a learning and reference resource.
Before working with this repository, you should have a basic development environment.
Recommended:
Node.js
npm
Git
A code editor
A modern web browser
You can verify your installation with:
node --version
npm --version
git --versionIf the commands return version numbers, the required tools are available.
Clone the repository with Git:
git clone <repository-url>Move into the project directory:
cd javascript-referenceReplace <repository-url> with the actual repository URL.
If the project has dependencies listed in package.json, install them with:
npm installThis creates the local node_modules directory and installs the packages defined by the project.
If the repository currently contains no runtime dependencies, this step may complete without installing additional packages.
Open the project in your editor.
For Visual Studio Code:
code .The project root should look similar to:
javascript-reference/
├── .gitignore
├── GETTING-STARTED.md
├── package.json
├── README.md
├── docs/
├── examples/
└── projects/
The repository is organized into several layers.
docs/
→ Main learning and reference material
examples/
→ Small focused demonstrations
projects/
→ Larger practical implementations
At the root:
README.md
→ Project overview
GETTING-STARTED.md
→ Setup and usage guide
package.json
→ Project metadata and scripts
The recommended starting point is:
docs/01-fundamentals/
Start with:
01-introduction-to-js.md
Then continue with:
02-variables.md
03-data-types.md
04-operators.md
05-control-flow.md
These topics provide the foundation for the rest of the repository.
After fundamentals, move to:
docs/02-functions/
Recommended order:
01-functions.md
02-arrow-functions.md
03-higher-order-functions.md
04-scope-closures.md
Functions are a central part of modern JavaScript, so this section should be understood before moving deeply into asynchronous programming.
Next:
docs/03-async/
Recommended order:
01-callbacks.md
02-promises.md
03-async-await.md
04-error-handling.md
This section becomes especially important when working with APIs, network requests, React applications, Next.js, and backend services.
Continue with:
docs/04-oop/
The section progresses from JavaScript objects to more advanced OOP concepts.
Recommended progression:
Objects
↓
Properties and Methods
↓
this
↓
Constructor Functions
↓
Prototypes
↓
Classes
↓
Constructors
↓
Methods
↓
Inheritance
↓
Private Fields
↓
Getters and Setters
↓
Polymorphism
↓
Encapsulation
↓
Abstraction
↓
Composition
↓
Best Practices
Do not focus only on memorizing class syntax.
Understand JavaScript's underlying object and prototype model as well.
Next:
docs/05-es6-features/
This section contains many features that appear frequently in modern codebases.
Important topics include:
let / const
Template literals
Destructuring
Spread
Rest
Default parameters
for...of
Map
Set
Modules
Optional chaining
Nullish coalescing
Logical assignment
BigInt
Private class features
These features are important for modern JavaScript development.
After understanding the JavaScript language itself, continue with:
docs/06-DOM/
A recommended order is:
DOM Introduction
↓
Selecting Elements
↓
Traversing Elements
↓
Manipulating Content
↓
Manipulating Attributes
↓
Manipulating Styles
↓
Creating and Removing Elements
↓
Events
↓
Event Object
↓
Bubbling and Capturing
↓
Event Delegation
↓
Forms and Inputs
↓
classList
↓
dataset
↓
Collections and NodeLists
↓
Fragments
↓
Observers
↓
Performance
↓
Security
↓
Practical Patterns
↓
Best Practices
This section connects JavaScript with the actual web page.
After the DOM, continue with:
docs/07-BOM/
The section covers browser-level capabilities such as:
window
location
history
navigator
screen
storage
timers
URL
browser events
clipboard
geolocation
notifications
security
performance
The recommended progression is:
window
↓
window properties
↓
window methods
↓
location
↓
history
↓
navigator
↓
screen
↓
storage
↓
timers
↓
dialogs
↓
URL / URLSearchParams
↓
online / offline
↓
browser events
↓
clipboard
↓
geolocation
↓
notifications
↓
security
↓
performance
↓
practical patterns
↓
best practices
A useful mental model is:
JavaScript
│
├── DOM
│ └── Web page/document
│
└── Browser APIs / BOM
└── Browser environment
Examples of DOM-related work:
document.querySelector(".button");
element.textContent = "Hello";Examples of browser-level work:
window.location.href;
localStorage.getItem("theme");
navigator.onLine;
window.innerWidth;
history.back();The two areas are related, but they solve different problems.
Each major directory contains a:
00-README.md
For example:
docs/01-fundamentals/00-README.md
docs/02-functions/00-README.md
docs/03-async/00-README.md
docs/04-oop/00-README.md
docs/05-es6-features/00-README.md
docs/06-DOM/00-README.md
docs/07-BOM/00-README.md
These files provide an overview of the section and help explain how the individual topics relate to each other.
Read the section README before starting a new major area.
Do not simply read a file from beginning to end and move on.
A stronger process is:
Read
↓
Understand
↓
Run the examples
↓
Change the examples
↓
Create your own variation
↓
Explain the concept in your own words
↓
Solve a small problem
↓
Review common mistakes
For example, after learning destructuring, do not stop after reading:
const { name, role } = user;Change the example.
Try:
const user = {
name: "Osama Abu Motlaq",
role: "Developer",
country: "Palestine",
};
const {
name,
role,
country,
} = user;
console.log(name);
console.log(role);
console.log(country);Then experiment with:
- default values
- nested objects
- renamed variables
- function parameters
- arrays
The goal is active understanding.
For simple JavaScript files, you can run them with Node.js.
Example:
node example.jsFor example:
const name = "Osama Abu Motlaq";
console.log(`Hello, ${name}!`);Running:
node example.jsproduces:
Hello, Osama Abu Motlaq!
DOM and browser API examples usually require a browser because Node.js does not provide the complete browser environment.
For example:
document.querySelector("button");requires a document.
Likewise:
window.innerWidth;
navigator.clipboard;
localStorage;are browser-related APIs.
For these examples, use:
- an HTML file
- browser DevTools
- the browser console
- a small local page
- a suitable development server
Modern browser DevTools are an important part of learning JavaScript.
Useful areas include:
Console
Elements
Network
Application
Sources
Performance
Security
For DOM topics, use:
Elements
Console
For browser storage:
Application
For network requests:
Network
For performance:
Performance
Do not rely exclusively on theoretical explanations.
Inspect what the browser actually does.
The browser console is useful for quickly testing browser APIs.
Examples:
window.innerWidthnavigator.onLinelocation.hreflocalStorage.setItem("theme", "dark")localStorage.getItem("theme")This is useful when learning browser behavior without creating a complete project.
A good learning habit is to intentionally modify examples.
Suppose the documentation contains:
const numbers = [1, 2, 3];
const doubled = numbers.map((number) => {
return number * 2;
});Do not only copy it.
Change it:
const numbers = [10, 20, 30];
const doubled = numbers.map((number) => {
return number * 2;
});
console.log(doubled);Then test your own variations.
Programming knowledge becomes stronger through experimentation.
You do not need to memorize every method or browser API.
Focus on understanding:
What problem does it solve?
Why does it exist?
What does it return?
What inputs does it accept?
What can fail?
When should I use it?
When should I not use it?
Once the concept is understood, syntax can be looked up when necessary.
After learning a topic, the repository becomes a lookup tool.
For example:
Forgot how closures work?
→ docs/02-functions/04-scope-closures.md
Forgot Promise chaining?
→ docs/03-async/02-promises.md
Forgot private class fields?
→ docs/04-oop/11-private-fields.md
Forgot optional chaining?
→ docs/05-es6-features/19-optional-chaining.md
Forgot event delegation?
→ docs/06-DOM/11-dom-event-delegation.md
Forgot localStorage behavior?
→ docs/07-BOM/08-browser-storage.md
The repository should become something you return to rather than something you read once.
Examples should answer a specific question.
A useful example:
const user = {
name: "Osama Abu Motlaq",
};
const { name } = user;
console.log(name);An unnecessary example would combine:
- destructuring
- classes
- promises
- DOM manipulation
- storage
- routing
all at once when the goal is only to explain destructuring.
Keep examples focused when studying individual concepts.
Projects are where concepts should start coming together.
For example, a project may combine:
Functions
+
Objects
+
Arrays
+
DOM
+
Events
+
Async JavaScript
+
Browser APIs
Projects should not merely repeat documentation examples.
They should require you to make decisions and solve problems.
A practical JavaScript learning loop is:
Learn a concept
↓
Write it manually
↓
Change the code
↓
Break the code intentionally
↓
Understand the error
↓
Build a small example
↓
Use the concept in a project
↓
Review the documentation later
The most important step is writing and changing the code yourself.
AI can be useful as a learning assistant, but it should not replace understanding.
A productive workflow is:
Try the problem yourself
↓
Get stuck
↓
Ask for an explanation or hint
↓
Understand the reasoning
↓
Write the solution yourself
↓
Compare approaches
↓
Refactor if necessary
Avoid copying code without understanding:
"Generate everything"
↓
"Paste everything"
↓
"Hope it works"
That may produce a working application without producing strong programming knowledge.
Use AI to:
- explain unfamiliar concepts
- review your code
- identify bugs
- compare approaches
- generate exercises
- ask follow-up questions
- explain browser behavior
The final goal is understanding, not simply obtaining code.
This repository is especially useful before and alongside React learning.
A strong foundation includes:
Variables
Functions
Arrow functions
Objects
Arrays
Destructuring
Spread
Modules
Higher-order functions
Closures
Promises
async / await
Error handling
DOM events
Browser APIs
These concepts appear frequently in React development.
For example:
JavaScript functions
↓
React components
Closures
↓
Hooks and callbacks
Array methods
↓
Rendering lists
Objects
↓
Props and state
Destructuring
↓
Props and hooks
Promises / async
↓
API requests
Modules
↓
Component organization
Browser APIs
↓
Client-side functionality
You do not need to master every advanced JavaScript feature before learning React.
A practical foundation is:
Fundamentals
+
Functions
+
Objects / Arrays
+
Modern syntax
+
Modules
+
Promises / async / await
+
Basic DOM and events
Once these are comfortable, React becomes much easier to understand.
Advanced JavaScript concepts can continue to be studied alongside React.
Next.js builds on top of React and JavaScript.
Before going deeply into Next.js, be comfortable with:
JavaScript fundamentals
React fundamentals
Components
Props
State
Events
Lists
Conditional rendering
Hooks
Forms
Routing concepts
Async JavaScript
API communication
Then Next.js concepts such as:
Server Components
Client Components
Routing
Layouts
Server-side rendering
Data fetching
Route handlers
Server actions
become easier to understand because the underlying JavaScript concepts are already familiar.
When making changes to the repository:
Check the current state:
git statusReview your changes:
git diffStage the changes:
git add .Create a commit:
git commit -m "docs: update JavaScript reference"Push the changes:
git pushKeep commits focused when possible.
For example:
docs: add browser storage reference
docs: improve async JavaScript examples
docs: add BOM best practices
is easier to understand than a large commit containing unrelated changes.
Before committing a new or modified file, check:
Correct filename
Correct folder
Consistent heading structure
Valid Markdown
Working code examples
No accidental non-technical text
No broken links
No duplicated sections
No unrelated changes
For code examples, make sure syntax is correct before committing.
Suppose you want to add a new topic to:
docs/07-BOM/
Follow the existing numbering convention.
For example:
21-new-topic.md
Then document:
What it is
Why it exists
Syntax
How it works
Practical examples
Common mistakes
Security considerations
Performance considerations
React / Next.js relevance when appropriate
Best practices
Quick reference
Key takeaways
The exact structure can vary depending on the topic, but explanations should remain practical and detailed.
If an entirely new category is required, follow the existing structure:
08-new-section/
├── 00-README.md
├── 01-topic.md
├── 02-topic.md
└── ...
The section README should explain:
- the purpose of the section
- the recommended learning order
- the topics covered
- how the section connects to JavaScript development
Use lowercase descriptive names.
Examples:
01-introduction-to-js.md
03-higher-order-functions.md
04-scope-closures.md
11-url-and-urlsearchparams.md
20-bom-best-practices.md
Use hyphens between words.
Avoid unnecessary spaces or inconsistent naming.
Use:
# Main Title
## Section
### SubsectionUse fenced code blocks:
```js
const name = "Osama Abu Motlaq";
console.log(name);
```Use inline code for JavaScript identifiers:
`localStorage`
`Promise`
`async`
`await`Keep code readable and focused.
A practical workflow is:
Choose a topic
↓
Read the section README
↓
Read the topic
↓
Run the examples
↓
Modify the examples
↓
Create your own experiment
↓
Build a small exercise
↓
Review the topic
↓
Move to the next topic
After completing several topics:
Build a project
↓
Encounter a problem
↓
Return to the reference
↓
Review the relevant concept
↓
Apply it to the project
This creates a continuous connection between theory and practice.
Verify that Node.js is installed:
node --versionIf the command is unavailable, install Node.js and restart the terminal.
Check:
npm --versionIf unavailable, verify the Node.js installation and your system PATH.
Check:
git --versionIf unavailable, install Git and restart the terminal.
This is expected for many browser APIs.
For example:
window
document
navigator.geolocation
localStorageare browser-related APIs and may not exist in Node.js.
Run browser examples inside a browser environment.
This usually means code intended for a browser is executing in an environment where window does not exist.
Check whether the code is running:
Browser
or:
Node.js / server
In React or Next.js, make sure browser-dependent logic runs on the client when required.
localStorage is a browser API.
Browser-specific access should happen in a browser environment.
In frameworks supporting server rendering, avoid accessing it during server execution.
Check:
Secure context
Browser support
Permission state
User interaction
and always handle failure.
Check:
HTTPS
Browser support
Permission
Location services
User settings
Do not assume the API will always return a position.
As the repository grows:
- Keep topics focused.
- Avoid duplicated explanations.
- Update outdated examples.
- Remove obsolete APIs when necessary.
- Improve examples based on practical experience.
- Keep section READMEs synchronized with their contents.
- Add projects that reinforce documented concepts.
- Periodically review browser APIs and JavaScript features.
A reference repository should evolve rather than accumulate outdated information.
01 Fundamentals
↓
02 Functions
↓
03 Async JavaScript
↓
04 OOP
↓
05 ES6+ Features
↓
06 DOM
↓
07 BOM
↓
Advanced
↓
Best Practices
↓
Examples
↓
Projects
This is a recommended path, not a strict requirement.
Once the fundamentals are comfortable, individual topics can be studied independently as needed.
For the simplest workflow:
git clone <repository-url>
cd javascript-reference
npm installThen open:
README.md
and start with:
docs/01-fundamentals/00-README.md
Follow the documentation progressively and run the examples yourself.
Do not measure progress only by the number of files you have read.
A stronger sign of progress is being able to:
Explain a concept
↓
Write it without copying
↓
Modify it
↓
Debug it
↓
Recognize when to use it
↓
Recognize when not to use it
↓
Apply it inside a project
The purpose of this repository is to build that level of understanding.
Use the documentation as a reference, but let experimentation and projects turn that knowledge into actual programming ability.