Improve getting started #462

delvedor · 2017-11-13T15:08:17Z

Fastify has different concepts that are not present in the other frameworks and our getting started section is failing to show them and give a gentle introduction to the framework.
This pr aims to fix that, please review it :)

mcollina · 2017-11-13T15:10:48Z

docs/Getting-Started.md

+```js
+const fastify = require('fastify')()
+
+fastify.register(require('./our-db-connector'), {


we should note somewhere that there is fastify-mongodb

mcollina · 2017-11-13T15:11:21Z

docs/Getting-Started.md

-<a name="schema"></a>
-### Schema serialization
-Fastify is designed for performance. To truly turbocharge our server, we can serialize responses according to the [JSON Schema](http://json-schema.org/) standard:
+Do you prefer to use `async/await`? We got you covered.


we should recommend https://github.com/mcollina/make-promises-safe

mcollina

LGTM

jsumners

I am not finished reviewing, and will surely find more changes to request. But it's time for me to head to lunch and I wanted to give you some feedback while you still have time to consider it and incorporate it given our timezone difference. So I'm submitting halfway through my review.

jsumners · 2017-11-13T15:57:13Z

docs/Getting-Started.md

@@ -1,13 +1,18 @@
 <h1 align="center">Fastify</h1>

 ## Getting Started
+Hello! Thank you for checking out Fastify!  
+This document aims to be a gentle introduction to the framework and its features. You will find some easy explanation, examples and link to other parts of the documentation if you want to get deepen in some argument.  


This document aims to be a gentle introduction to the framework and its features. ~~You will find some easy explanation,~~ It is an elementary introduction with examples and links to other parts of the documentation. ~~if you want to get deepen in some argument.~~

jsumners · 2017-11-13T15:58:49Z

docs/Getting-Started.md

-<a name="schema"></a>
-### Schema serialization
-Fastify is designed for performance. To truly turbocharge our server, we can serialize responses according to the [JSON Schema](http://json-schema.org/) standard:
+Do you prefer to use `async/await`? We got you covered.  


Do you prefer to use async/await? ~~We got you covered~~ Fastify supports it out-of-the-box.

jsumners · 2017-11-13T15:59:31Z

docs/Getting-Started.md

-### Schema serialization
-Fastify is designed for performance. To truly turbocharge our server, we can serialize responses according to the [JSON Schema](http://json-schema.org/) standard:
+Do you prefer to use `async/await`? We got you covered.  
+*(we also suggest to use [make-promises-safe](https://github.com/mcollina/make-promises-safe) to avoid file descriptor and memory leaks)*


(we also suggest ~~to use~~ using make-promises-safe to avoid file descriptor and memory leaks)

jsumners · 2017-11-13T16:00:43Z

docs/Getting-Started.md

-// Declare a route with an output schema
-fastify.get('/', opts, function (request, reply) {
-  reply.send({ hello: 'world' })
+fastify.get('/', async (request, reply) => {


Does the reply parameter even need to be supplied?

Yes, if you need to set some custom header o change the status code.

Then maybe a note about it and why it isn't being used here would be good to have.

I agree that a note could be a nice idea, but I think that this document should provide just a getting started, we have provided the link to other parts of the documentation that explains better the usage of every api. I don't think that add here too many info could be a good idea.

jsumners · 2017-11-13T16:02:11Z

docs/Getting-Started.md

@@ -56,61 +44,167 @@ fastify.listen(3000, function (err) {
 })
 ```

-*To learn more about using serialization and validation, see [Validation and Serialization](https://github.com/fastify/fastify/blob/master/docs/Validation-and-Serialization.md)!*
+Awesome, that was easy.  
+Unfortunately, write a complex application requires definitely more code than what we wrote above. A classic problem when you are building a new application is how handle multiple files, asynchronous bootstrapping and the architecture of your code.  


Unfortunately, ~~write~~ writing a complex application requires ~~definitely~~ significantly more code than ~~what we wrote above~~ this example.

jsumners · 2017-11-13T16:05:35Z

docs/Getting-Started.md

 ### Install
 ```
 npm i fastify --save
 ```
+<a name="first-server"></a>


=> <a id="first-server"></a>

jsumners · 2017-11-13T16:06:21Z

docs/Getting-Started.md

-<a name="register"></a>
-### Register
-As you can see, using Fastify is very easy and handy. Obviously, registering all of your routes in the same file is not a good idea, so Fastify offers a utility to solve this problem, `register`:
+<a name="first-plugin"></a>


=> <a id="first-plugin"></a>

jsumners · 2017-11-13T16:07:23Z

docs/Getting-Started.md

-As you can see, using Fastify is very easy and handy. Obviously, registering all of your routes in the same file is not a good idea, so Fastify offers a utility to solve this problem, `register`:
+<a name="first-plugin"></a>
+### Your first plugin
+As in javascript everything is an object, in Fastify everything is a plugin.  


As ~~in javascript~~ with Javascript where everything is an object, in with Fastify everything is a plugin.

jsumners · 2017-11-13T16:08:19Z

docs/Getting-Started.md

+### Your first plugin
+As in javascript everything is an object, in Fastify everything is a plugin.  
+Before digging into it, let's see how it works!  
+Let's declare our basic server, but instead of declare the route inside the entry point, we'll declare it in an external file (checkout the [route declaration](https://github.com/fastify/fastify/blob/master/docs/Routes.md) docs).


Let's declare our basic server, but instead of ~~declare~~ declaring the route inside the entry point, we'll declare it in an external file (checkout the route declaration docs).

jsumners · 2017-11-13T16:10:34Z

docs/Getting-Started.md

-  if (err) throw err
+module.exports = routes
+```
+As you can see we used the `register` api, that you will use a lot when working with Fastify, since is the only way to register routes, plugins and so on.  


~~As you can see~~ In this example we used the register ~~api~~ API. ~~, that you will use a lot when working with Fastify, since is the only way to register routes, plugins and so on.~~ This API is the core of the Fastify framework, and is the only way to register routes, plugins and so on.

delvedor · 2017-11-13T16:19:43Z

@jsumners I have addressed almost all your suggestions, thanks!

jsumners · 2017-11-13T17:35:42Z

docs/Getting-Started.md

-  if (err) throw err
+module.exports = routes
+```
+In this we used the `register` API. This API is the core of the Fastify framework, and is the only way to register routes, plugins and so on. 


In this [example] we used...

jsumners · 2017-11-13T17:37:57Z

docs/Getting-Started.md

+```
+In this we used the `register` API. This API is the core of the Fastify framework, and is the only way to register routes, plugins and so on. 
+
+At the beginning of this document we said that Fastify helps you on handling the asynchronous bootstrapping of your application. Why this is important?  


At the beginning of this ~~document~~ guide we ~~said~~ noted that Fastify ~~helps you on handling~~ provides a foundation that assists with the asynchronous bootstrapping of ~~your~~ an application. Why this is important?

jsumners · 2017-11-13T17:40:45Z

docs/Getting-Started.md

+In this we used the `register` API. This API is the core of the Fastify framework, and is the only way to register routes, plugins and so on. 
+
+At the beginning of this document we said that Fastify helps you on handling the asynchronous bootstrapping of your application. Why this is important?  
+Well, let's say you must connect to database to fetch some data, obviously you don't want that the server starts accept requests before the database connection has been established. How can you address this problem?  


Well, let's say you must connect to database to fetch some data, obviously you don't want that the server starts accept requests before the database connection has been established. How can you address this problem?

Consider the scenario where a database connection is needed to handle data storage. Obviously the database connection needs to be available prior to the server accepting connections. How do we address this problem?

jsumners · 2017-11-13T17:41:52Z

docs/Getting-Started.md

+
+At the beginning of this document we said that Fastify helps you on handling the asynchronous bootstrapping of your application. Why this is important?  
+Well, let's say you must connect to database to fetch some data, obviously you don't want that the server starts accept requests before the database connection has been established. How can you address this problem?  
+Usually you will work with some complex callback/promises system that will mix the framework api with other libraries and your code.  


~~Usually you will work with some complex callback/promises system that will mix the framework api with other libraries and your code.~~

A typical solution is to use a complex callback, or promises, system that will mix the framework API with other libraries and the application code.

jsumners · 2017-11-13T17:42:28Z

docs/Getting-Started.md

+At the beginning of this document we said that Fastify helps you on handling the asynchronous bootstrapping of your application. Why this is important?  
+Well, let's say you must connect to database to fetch some data, obviously you don't want that the server starts accept requests before the database connection has been established. How can you address this problem?  
+Usually you will work with some complex callback/promises system that will mix the framework api with other libraries and your code.  
+Fastify handles this internally for you, with the minimum effort!


Fastify handles this internally ~~for you,~~ with ~~the~~ minimum effort!

jsumners · 2017-11-13T18:04:40Z

docs/Getting-Started.md

+<a name="extend-server"></a>
+### Extend your server
+Fastify is built to be extremely extensible and it's very minimal, we believe that provide a fully featured framework is not needed, since it will probably give you more than what you need.  
+In other words, Fastify is not batteries included and if you need them, checkout our amazing [ecosystem](https://github.com/fastify/fastify/blob/master/docs/Ecosystem.md)!


In other words, Fastify is not ~~batteries included~~ a "batteries included" framework, and ~~if you need them, checkout our~~ relies on an amazing ecosystem!

jsumners · 2017-11-13T18:05:48Z

docs/Getting-Started.md

+
+<a name="test-server"></a>
+### Test your server
+We not offer a testing framework, but we do recommend a way to write your test that uses in a smart way the features and the architecture of Fastify.  


~~We not~~ Fastify does not offer a testing framework, but we do recommend a way to write your ~~test~~ tests that uses ~~in a smart way~~ the features and the architecture of Fastify.

jsumners · 2017-11-13T18:06:21Z

docs/Getting-Started.md

+<a name="test-server"></a>
+### Test your server
+We not offer a testing framework, but we do recommend a way to write your test that uses in a smart way the features and the architecture of Fastify.  
+Checkout the [testing](https://github.com/fastify/fastify/blob/master/docs/Testing.md) documentation!


~~Checkout the testing documentation!~~

Read the testing documentation to learn more.

jsumners · 2017-11-13T18:07:45Z

docs/Getting-Started.md

-### Run from CLI
-You can also run Fastify from the CLI thanks to [fastify-cli](https://github.com/fastify/fastify-cli). It's very easy! Simply add the following lines to your `package.json`:
+### Run your server from CLI
+You can also run Fastify from the CLI thanks to [fastify-cli](https://github.com/fastify/fastify-cli). It's very easy!  


~~You can also run~~ Fastify also has ~~from the~~ CLI integration thanks to fastify-cli. It's very easy!

jsumners · 2017-11-13T18:08:00Z

docs/Getting-Started.md

-You can also run Fastify from the CLI thanks to [fastify-cli](https://github.com/fastify/fastify-cli). It's very easy! Simply add the following lines to your `package.json`:
+### Run your server from CLI
+You can also run Fastify from the CLI thanks to [fastify-cli](https://github.com/fastify/fastify-cli). It's very easy!  
+Simply add the following lines to your `package.json`:


Simply add the following lines to ~~your~~ package.json:

allevo

Good work (as always)!

allevo · 2017-11-13T15:27:15Z

docs/Getting-Started.md


-fastify.listen(8000, function (err) {
+fastify.listen(3000, function (err) {
  if (err) throw err
  console.log(`server listening on ${fastify.server.address().port}`)


fastify.log.info('...')?

allevo · 2017-11-13T21:07:42Z

docs/Getting-Started.md

-### Schema serialization
-Fastify is designed for performance. To truly turbocharge our server, we can serialize responses according to the [JSON Schema](http://json-schema.org/) standard:
+Do you prefer to use `async/await`? Fastify supports it out-of-the-box.  
+*(we also suggest using [make-promises-safe](https://github.com/mcollina/make-promises-safe) to avoid file descriptor and memory leaks)*


This is out of the context. Maybe a recommendation is better for this tips

allevo · 2017-11-13T21:10:05Z

docs/Getting-Started.md

@@ -56,61 +44,167 @@ fastify.listen(3000, function (err) {
 })
 ```

-*To learn more about using serialization and validation, see [Validation and Serialization](https://github.com/fastify/fastify/blob/master/docs/Validation-and-Serialization.md)!*
+Awesome, that was easy.  
+Unfortunately, writing a complex application requires significantly more code than this example. A classic problem when you are building a new application is how handle multiple files, asynchronous bootstrapping and the architecture of your code.  


a new application is how handle multiple files => a new application is how handling multiple files

allevo · 2017-11-13T21:11:05Z

docs/Getting-Started.md

-*To learn more about using serialization and validation, see [Validation and Serialization](https://github.com/fastify/fastify/blob/master/docs/Validation-and-Serialization.md)!*
+Awesome, that was easy.  
+Unfortunately, writing a complex application requires significantly more code than this example. A classic problem when you are building a new application is how handle multiple files, asynchronous bootstrapping and the architecture of your code.  
+Fastify offers an easy platform that helps solve all of problems, and more.


that helps solve => that helps solving

Or add a "these" between "of" and "problems".

allevo · 2017-11-13T21:14:40Z

docs/Getting-Started.md

-  something: true
+fastify.listen(3000, function (err) {
+  if (err) throw err
+  console.log(`server listening on ${fastify.server.address().port}`)


fastify.log.info ?

allevo · 2017-11-13T21:23:52Z

docs/Getting-Started.md

+Fastify is built to be extremely extensible and it's very minimal, we believe that provide a fully featured framework is not needed, since it will probably give you more than what you need.  
+In other words, Fastify is not batteries included and if you need them, checkout our amazing [ecosystem](https://github.com/fastify/fastify/blob/master/docs/Ecosystem.md)!
+
+<a name="test-server"></a>


=> <a id="test-server"></a>

allevo · 2017-11-13T21:25:08Z

docs/Getting-Started.md

+### Test your server
+We not offer a testing framework, but we do recommend a way to write your test that uses in a smart way the features and the architecture of Fastify.  
+Checkout the [testing](https://github.com/fastify/fastify/blob/master/docs/Testing.md) documentation!
+
 <a name="cli"></a>


=><a id="cli"></a>

allevo · 2017-11-13T21:26:05Z

docs/Plugins-Guide.md

@@ -271,6 +270,26 @@ module.exports = fp(dbPlugin)
 ```
 You can also tell to `fastify-plugin` to check the installed version of Fastify, in case of you need a specific api.

+<a name="handle-errors"></a>


=> <a id="handle-errors"></a>

allevo · 2017-11-13T21:30:16Z

docs/Routes.md

+<a name="url-building"></a>
+### Url building
+Fastify supports both static and dynamic urls.  
+To register a **parametric** path, use the *colon* before the parameter name. For **wildcard** use the *star*.


=> To register a **parametric** path, use the *colon* (`:`) before the parameter name. For **wildcard** use the *star*` (`*`)

I don't think this is needed, there is an example few line below and everybody know what is a column and what is a star :P

"star" => "asterisk"

allevo · 2017-11-13T21:32:38Z

docs/Routes.md

+In this case as parameter separator it's possible to use whatever character is not matched by the regular expression.
+
+Having a route with multiple parameters may affect negatively the performance, so prefer single parameter approach whenever possible, especially on routes which are on the hot path of your application.
+If you are interested hon how we handle the routing, checkout [find-my-way](https://github.com/delvedor/find-my-way).


=> If you are interested in

delvedor · 2017-11-14T09:57:46Z

I've addressed almost all suggestions, please take a final look :)

github-actions · 2022-02-23T00:19:41Z

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.

delvedor added documentation Improvements or additions to documentation enhancement labels Nov 13, 2017

delvedor requested review from mcollina, jsumners, allevo and StarpTech November 13, 2017 15:08

mcollina reviewed Nov 13, 2017

View reviewed changes

delvedor force-pushed the improve-getting-started branch from 0011022 to cfc5ccf Compare November 13, 2017 15:24

mcollina approved these changes Nov 13, 2017

View reviewed changes

jsumners requested changes Nov 13, 2017

View reviewed changes

delvedor force-pushed the improve-getting-started branch from cfc5ccf to b96daf8 Compare November 13, 2017 16:19

jsumners requested changes Nov 13, 2017

View reviewed changes

allevo reviewed Nov 13, 2017

View reviewed changes

Updated documentation

f5e0687

delvedor force-pushed the improve-getting-started branch from b96daf8 to f5e0687 Compare November 13, 2017 21:56

jsumners approved these changes Nov 14, 2017

View reviewed changes

delvedor merged commit 2b962a8 into master Nov 14, 2017

delvedor deleted the improve-getting-started branch November 14, 2017 15:28

github-actions bot locked as resolved and limited conversation to collaborators Feb 23, 2022

Eomm added the semver-minor Issue or PR that should land as semver minor label Apr 1, 2023

Improve getting started #462

Improve getting started #462

Conversation

delvedor commented Nov 13, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mcollina left a comment

Choose a reason for hiding this comment

jsumners left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

delvedor commented Nov 13, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

allevo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

delvedor commented Nov 14, 2017

github-actions bot commented Feb 23, 2022