Skip to content

Commit 0baf014

Browse files
MylesBorinsamiller-gh
MylesBorins
authored and
amiller-gh
committed
docs: Vendor in documentation.
1 parent 2bd3744 commit 0baf014

81 files changed

Lines changed: 11616 additions & 5545 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎gatsby-config.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ module.exports = {
2020
resolve: `gatsby-source-filesystem`,
2121
options: {
2222
name: `learn`,
23-
path: `${__dirname}/node_modules/website-redesign/documentation/`,
23+
path: `${__dirname}/src/documentation/`,
2424
include: [`**/*.md`], // ignore files starting with a dot
2525
},
2626
},

‎package-lock.json‎

Lines changed: 5936 additions & 5542 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,7 @@
2828
"react-emotion": "^9.2.12",
2929
"react-helmet": "^5.2.0",
3030
"tslint": "^5.11.0",
31-
"typescript": "^3.1.1",
32-
"website-redesign": "nodejs/website-redesign#f8fdb87d"
31+
"typescript": "^3.1.1"
3332
},
3433
"keywords": [
3534
"gatsby",

‎src/documentation/0000-template/article.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
- **Start Date:** (fill me in with today's date, YYYY-MM-DD)
2+
- **PR:** (leave this empty)
3+
- **Issue:** [#0000](link-to-issue) (remove if no associated issue)
4+
- **Keywords:** (4-8 keywords for page meta data)
5+
- **Summary:** (~60 character explanation of the article content for page meta data)
6+
7+
# Title
8+
9+
> Introduction paragraph(s).
10+
11+
## Body Content
12+
13+
> Body content, including sub-headings (H3 or lower, using the appropriate H(n) level for the content's place in the document), prose, code samples, screenshots, etc.
14+
15+
> Note: any included screenshots for your article should be saved in the same directory your article.md lives in!
16+
17+
## Conclusion
18+
19+
> 1-2 paragraphs wrapping up the article

‎src/documentation/0001-node-introduction/async.png‎

20.7 KB
Loading

‎src/documentation/0001-node-introduction/fast.png‎

17.6 KB
Loading

‎src/documentation/0001-node-introduction/index.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
title: Introduction to Node.js
3+
description: "This post is a getting started guide to Node.js, the server-side JavaScript runtime environment. Node.js is built on top of the Google Chrome V8 JavaScript engine, and it's mainly used to create web servers - but it's not limited to that"
4+
author: flaviocopes
5+
---
6+
7+
<!-- TOC -->
8+
9+
- [Overview](#overview)
10+
- [The best features of Node.js](#the-best-features-of-nodejs)
11+
- [Fast](#fast)
12+
- [Simple](#simple)
13+
- [JavaScript](#javascript)
14+
- [V8](#v8)
15+
- [Asynchronous platform](#asynchronous-platform)
16+
- [A huge number of libraries](#a-huge-number-of-libraries)
17+
- [An example Node.js application](#an-example-nodejs-application)
18+
- [Node.js frameworks and tools](#nodejs-frameworks-and-tools)
19+
20+
<!-- /TOC -->
21+
22+
## Overview
23+
24+
Node.js is a **runtime environment for JavaScript** that runs on the **server**.
25+
26+
Node.js is open source, cross-platform, and since its introduction in 2009, it got hugely popular and now plays a significant role in the web development scene. If GitHub stars are one popularity indication factor, having 46000+ stars means being very popular.
27+
28+
Node.js is built on top of the Google Chrome V8 JavaScript engine, and it's mainly used to create web servers - but it's not limited to that.
29+
30+
## The best features of Node.js
31+
32+
### Fast
33+
34+
![Fast](fast.png)
35+
36+
One of the main selling points of Node.js is **speed**. JavaScript code running on Node.js (depending on the benchmark) can be twice as fast than compiled languages like C or Java, and orders of magnitude faster than interpreted languages like Python or Ruby, because of its non-blocking paradigm.
37+
38+
### Simple
39+
40+
Node.js is simple. Extremely simple, actually.
41+
42+
### JavaScript
43+
44+
Node.js runs JavaScript code. This means that millions of frontend developers that already use JavaScript in the browser are able to run the server-side code and frontend-side code using the same programming language without the need to learn a completely different tool.
45+
46+
The paradigms are all the same, and in Node.js the new ECMAScript standards can be used first, as you don't have to wait for all your users to update their browsers - you decide which ECMAScript version to use by changing the Node.js version.
47+
48+
### V8
49+
50+
Running on the Google V8 JavaScript engine, which is Open Source, Node.js is able to leverage the work of thousands of engineers that made (and will continue to make) the Chrome JavaScript runtime blazing fast.
51+
52+
### Asynchronous platform
53+
54+
![Async](async.png)
55+
56+
In traditional programming languages (C, Java, Python, PHP) all instructions are blocking by default unless you explicitly "opt in" to perform asynchronous operations. If you perform a network request to read some JSON, the execution of that particular thread is blocked until the response is ready.
57+
58+
**JavaScript allows to create asynchronous and non-blocking code in a very simple way**, by using a **single thread**, **callback functions** and **event-driven programming**. Every time an expensive operation occurs, we pass a callback function that will be called once we can continue with the processing. We're not waiting for that to finish before going on with the rest of the program.
59+
60+
Such mechanism derives from the browser. We can't wait until something loads from an AJAX request before being able to intercept click events on the page. **It all must happen in real time** to provide a good experience to the user.
61+
62+
> If you've created an onclick handler for a web page you've already used asynchronous programming techniques with event listeners.
63+
64+
This allows Node.js to handle thousands of concurrent connections with a single server without introducing the burden of managing threads concurrency, which would be a major source of bugs.
65+
66+
Node provides non-blocking I/O primitives, and generally, libraries in Node.js are written using non-blocking paradigms, making a blocking behavior an exception rather than the normal.
67+
68+
When Node.js needs to perform an I/O operation, like reading from the network, access a database or the filesystem, instead of blocking the thread Node.js will simply resume the operations when the response comes back, instead of wasting CPU cycles waiting.
69+
70+
### A huge number of libraries
71+
72+
npm with its simple structure helped the ecosystem of node.js proliferate and now the npm registry hosts almost 500.000 open source packages you can freely use.
73+
74+
## An example Node.js application
75+
76+
The most common example Hello World of Node.js is a web server:
77+
78+
```js
79+
const http = require('http')
80+
81+
const hostname = '127.0.0.1'
82+
const port = 3000
83+
84+
const server = http.createServer((req, res) => {
85+
res.statusCode = 200
86+
res.setHeader('Content-Type', 'text/plain')
87+
res.end('Hello World\n')
88+
})
89+
90+
server.listen(port, hostname, () => {
91+
console.log(`Server running at http://${hostname}:${port}/`)
92+
})
93+
```
94+
95+
To run this snippet, save it as a `server.js` file and run `node server.js` in your terminal.
96+
97+
This code first includes the Node.js [`http` module](https://nodejs.org/api/http.html).
98+
99+
Node.js has an amazing [standard library](https://nodejs.org/api/), including a first-class support for networking.
100+
101+
The `createServer()` method of `http` creates a new HTTP server and returns it.
102+
103+
The server is set to listen on the specified port and hostname. When the server is ready, the callback function is called, in this case informing us that the server is running.
104+
105+
Whenever a new request is received, the [`request` event](https://nodejs.org/api/http.html#http_event_request) is called, providing two objects: a request (an [`http.IncomingMessage`](https://nodejs.org/api/http.html#http_class_http_incomingmessage) object) and a response (an [`http.ServerResponse`](https://nodejs.org/api/http.html#http_class_http_serverresponse) object).
106+
107+
Those 2 objects are essential to handle the HTTP call.
108+
109+
The first provides the request details. In this simple example, this is not used, but you could access the request headers and request data.
110+
111+
The second is used to return data to the caller.
112+
113+
In this case with
114+
115+
```js
116+
res.statusCode = 200
117+
```
118+
119+
we set the statusCode property to 200, to indicate a successful response.
120+
121+
We set the Content-Type header:
122+
123+
```js
124+
res.setHeader('Content-Type', 'text/plain')
125+
```
126+
127+
and we end close the response, adding the content as an argument to `end()`:
128+
129+
```js
130+
res.end('Hello World\n')
131+
```
132+
133+
## Node.js frameworks and tools
134+
135+
Node.js is a low-level platform, and to make things easier and more interesting for developers thousands of libraries were built upon Node.js.
136+
137+
Many of those established over time as popular options. Here is a non-comprehensive list of the ones worth learning:
138+
139+
- [**Express**](https://expressjs.com/), one of the most simple yet powerful ways to create a web server. Its minimalist approach, unopinionated, focused on the core features of a server, is key to its success.
140+
- [**Meteor**](https://meteor.com), an incredibly powerful full-stack framework, powering you with an isomorphic approach to building apps with JavaScript, sharing code on the client and the server. Once an off-the-shelf tool that provided everything, now integrates with frontend libs React, [Vue](https://vuejs.org/) and Angular. Can be used to create mobile apps as well.
141+
- [**koa**](http://koajs.com/), built by the same team behind Express, aims to be even simpler and smaller, building on top of years of knowledge. The new project born out of the need to create incompatible changes without disrupting the existing community.
142+
- [**Next.js**](https://nextjs.org/), a framework to render server-side rendered [React](https://reactjs.org/) applications.
143+
- [**Micro**](https://github.com/zeit/micro), a very lightweight server to create asynchronous HTTP microservices.
144+
- [**Socket.io**](https://socket.io/), a real-time communication engine to build network applications.

‎src/documentation/0002-node-history/index.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
title: A brief history of Node.js
3+
description: 'A look back on the history of Node.js from 2009 to today'
4+
author: flaviocopes
5+
---
6+
7+
Believe it or not, Node.js is just 9 years old.
8+
9+
In comparison, JavaScript is 23 years old and the web as we know it (after the introduction of Mosaic) is 25 years old.
10+
11+
9 years is such a little amount of time for a technology, but Node.js seems to have been around forever.
12+
13+
I've had the pleasure to work with Node since the early days when it was just 2 years old, and despite the little information available, you could already feel it was a huge thing.
14+
15+
In this post, we want to draw the big picture of Node in its history, to put things in perspective.
16+
17+
<!-- TOC -->
18+
19+
- [A little bit of history](#a-little-bit-of-history)
20+
- [2009](#2009)
21+
- [2010](#2010)
22+
- [2011](#2011)
23+
- [2012](#2012)
24+
- [2013](#2013)
25+
- [2014](#2014)
26+
- [2015](#2015)
27+
- [2016](#2016)
28+
- [2017](#2017)
29+
- [2018](#2018)
30+
31+
<!-- /TOC -->
32+
33+
## A little bit of history
34+
35+
JavaScript is a programming language that was created at Netscape as a scripting tool to manipulate web pages inside their browser, [Netscape Navigator](https://en.wikipedia.org/wiki/Netscape_Navigator).
36+
37+
Part of the business model of Netscape was to sell Web Servers, which included an environment called _Netscape LiveWire_, which could create dynamic pages using server-side JavaScript. So the idea of server-side JavaScript was not introduced by Node.js, but it's old just like JavaScript - but at the time it was not successful.
38+
39+
One key factor that led to the rise of Node.js was timing. JavaScript since a few years was starting being considered a serious language, thanks for the "Web 2.0" applications that showed the world what a modern experience on the web could be like (think Google Maps or GMail).
40+
41+
The JavaScript engines performance bar raised considerably thanks to the browser competition battle, which is still going strong. Development teams behind each major browser work hard every day to give us better performance, which is a huge win for JavaScript as a platform. V8, the engine that Node.js uses under the hood, is one of those and in particular it's the Chrome JS engine.
42+
43+
But of course, Node.js is not popular just because of pure luck or timing. It introduced much innovative thinking on how to program in JavaScript on the server.
44+
45+
## 2009
46+
47+
Node.js is born
48+
The first form of npm is created
49+
50+
## 2010
51+
52+
Express is born
53+
[Socket.io](https://socket.io) is born
54+
55+
## 2011
56+
57+
npm hits 1.0
58+
Big companies start adopting Node: LinkedIn, Uber
59+
[Hapi](https://hapijs.com) is born
60+
61+
## 2012
62+
63+
Adoption continues very rapidly
64+
65+
## 2013
66+
67+
First big blogging platform using Node: Ghost
68+
[Koa](https://koajs.com/) is born
69+
70+
## 2014
71+
72+
The Big Fork: [io.js](https://iojs.org/) is a major fork of Node.js, with the goal of introducing ES6 support and moving faster
73+
74+
## 2015
75+
76+
The [Node.js Foundation](https://foundation.nodejs.org/) is born
77+
IO.js is merged back into Node.js
78+
npm introduces private modules
79+
Node 4 (no 1, 2, 3 versions were previously released)
80+
81+
## 2016
82+
83+
The [leftpad incident](https://blog.npmjs.org/post/141577284765/kik-left-pad-and-npm)
84+
Yarn is born
85+
Node 6
86+
87+
## 2017
88+
89+
npm focuses more on security
90+
Node 8
91+
HTTP/2
92+
V8 introduces Node in its testing suite, officially making Node a target for the JS engine, in addition to Chrome
93+
3 billion npm downloads every week
94+
95+
## 2018
96+
97+
Node 10
98+
ES modules .mjs experimental support

‎src/documentation/0003-node-installation/index.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: How to install Node.js
3+
description: 'How you can install Node.js on your system: a package manager, the official website installer or nvm'
4+
author: flaviocopes
5+
---
6+
7+
Node.js can be installed in different ways. This post highlights the most common and convenient ones.
8+
9+
Official packages for all the major platforms are available at <https://nodejs.org/en/download/>.
10+
11+
One very convenient way to install Node.js is through a package manager. In this case, every operating system has its own.
12+
13+
On macOS, [Homebrew](https://brew.sh/) is the de-facto standard, and - once installed - allows to install Node.js very easily, by running this command in the CLI:
14+
15+
```sh
16+
brew install node
17+
```
18+
19+
Other package managers for Linux and Windows are listed in <https://nodejs.org/en/download/package-manager/>
20+
21+
`nvm` is a popular way to run Node. It allows you to easily switch the Node version, and install new versions to try and easily rollback if something breaks, for example.
22+
23+
It is also very useful to test your code with old Node versions.
24+
25+
See <https://github.com/creationix/nvm> for more information about this option.
26+
27+
My suggestion is to use the official installer if you are just starting out and you don't use Homebrew already, otherwise, Homebrew is my favorite solution.
28+
29+
In any case, when Node is installed you'll have access to the `node` executable program in the command line.

‎src/documentation/0004-node-javascript-language/index.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: How much JavaScript do you need to know to use Node?
3+
description: 'If you are just starting out with JavaScript, how much deeply do you need to know the language?'
4+
author: flaviocopes
5+
---
6+
7+
As a beginner, it's hard to get to a point where you are confident enough in your programming abilities.
8+
9+
While learning to code, you might also be confused at where does JavaScript end, and where Node.js begins, and vice versa.
10+
11+
I would recommend you to have a good grasp of the main JavaScript concepts before diving into Node.js:
12+
13+
- Lexical Structure
14+
- Expressions
15+
- Types
16+
- Variables
17+
- Functions
18+
- this
19+
- Arrow Functions
20+
- Loops
21+
- Loops and Scope
22+
- Arrays
23+
- Template Literals
24+
- Semicolons
25+
- Strict Mode
26+
- ECMAScript 6, 2016, 2017
27+
28+
With those concepts in mind, you are well on your road to become a proficient JavaScript developer, in both the browser and in Node.js.
29+
30+
The following concepts are also key to understand asynchronous programming, which is one fundamental part of Node.js:
31+
32+
- Asynchronous programming and callbacks
33+
- Timers
34+
- Promises
35+
- Async and Await
36+
- Closures
37+
- The Event Loop

0 commit comments

Comments
 (0)