Skip to content

Commit cd863b7

Browse files
committed
ESM supported. Every file in the app folder will be registered as plugin. remove database initializing. dependencies updated.
1 parent 661aa25 commit cd863b7

File tree

9 files changed

+3122
-428
lines changed

9 files changed

+3122
-428
lines changed

.gitignore

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,6 @@ lerna-debug.log*
99

1010
node_modules
1111
.DS_Store
12-
dist
1312
dist-ssr
1413
coverage
1514
*.local

.npmignore

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,6 @@ lerna-debug.log*
99

1010
node_modules
1111
.DS_Store
12-
dist
1312
dist-ssr
1413
coverage
1514
*.local

README.md

Lines changed: 67 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,14 @@
22

33
## Description
44

5-
This is a simple fasitfy application skeleton for JSON API server with some pre-defined features.
5+
This is a simple file-based routing fasitfy application skeleton for JSON API server with some pre-defined features.
66

77
After calling the default exported function, the fastify server will listen on the specified host and port. The returned value of the function is a fastify instance. By default, this instance will also be registered to the global scope with variable name `app`. You can access it via `global.app` or just `app`. This name can be changed by setting the `app.globalAppVariable` in the config. To prevent this behavior, set the `app.disableGlobalAppVariable` to `true`.
88

9+
## File-based routing
10+
11+
Any `{.js, .mjs, .ts}` file in the `app` and it's subfolders of your project root that does not starts with underscore(`_`) will be registered as a fastify plugin. The subfolder name will be the prefix. For example, if you have an `app/user/api.js` or `app/user/other-file.mjs` file, you can access it via `http://localhost:port/user/YOUR-API`.
12+
913
## Reply helpers
1014

1115
There are some useful helpers can be used in the route handler. In the following example, the `req` is the first parameter of the handler, also know as `request`. The `res` is the second parameter of the handler function, also known as the `reply` object in fastify.
@@ -66,10 +70,6 @@ Generate an uncaught error response.
6670

6771
## Other features
6872

69-
### Database
70-
71-
If the `database` section is set in the config, it will also connect to the database using the `knex` package. The initialized knex instance will be stored in the `global.knex` variable in the process scope.
72-
7373
### Config object
7474

7575
The config object passed to the default exported function can be accessed via `app.config`
@@ -129,23 +129,20 @@ This handler can be disabled by setting the `app.disableApiErrorHandler` to `tru
129129

130130
By default, the server will log the API error(`throw new ApiError()`). This behavior can be disabled by setting the `app.disableLogApiError` to `true`.
131131

132-
### Orangize API prefix using folder
133-
134-
You can organize your API by putting them in different folders. The folder name will be the prefix of the API. For example, if you have an `app/user/api.js` file, you can access it via `http://localhost:port/user/YOUR-API`. Only the file with the `api.js` will be registered as fastify plugin.
135-
136132
## Usage
137133

138134
### Install
139135

140136
```bash
141137
npm install fastify-app js-yaml
138+
npm install knex mysql2 # if you want to use a database
142139
```
143140

144141
> **Note**
145142
>
146143
> The `js-yaml` can be omitted if you don't want to use a yaml config file.
147144
148-
### Create a config file (optional)
145+
### Create a config file
149146

150147
Create a `config.yaml` file in your project root with the following example:
151148

@@ -200,11 +197,11 @@ database:
200197
idleTimeoutMillis: 60000
201198
```
202199
203-
> If you don't want this package to connect to a database, just remove the `database` section from the config.
200+
### Create your first API endpoint
204201
205-
## Create your first API endpoint
202+
> CommonJS and ES module are both supported.
206203
207-
Create an `app` folder in your project root, and create an `api.js` file in it with the following content:
204+
Create an `app` folder in your project root, and create a js file in it, `api.js` for example (or `.mjs` or `.ts`), with the following content:
208205

209206
```javascript
210207
'use strict';
@@ -230,9 +227,62 @@ function plugin(fastify, opts, done) {
230227

231228
After starting the server, this API endpoint can be accssed via `http://host:port/ok`.
232229

233-
You can also create subfolders in the `app` folder to organize your API. If you have an `app/user/api.js` file, you can access it via `http://localhost:port/user/YOUR-API`.
230+
You can also create subfolders in the `app` folder to organize your API. If you have an `app/user/api.js` file, you can access it via `http://localhost:port/user/endpoint-in-api.js`.
231+
232+
Files with names starting with an underscore will not be registered to the fastify instance.
234233

235-
## Start the server
234+
### Start the server (CommonJS)
236235
```javascript
237-
require('fastify-app')(require('js-yaml').load(require('fs').readFileSync('./config.yaml', 'utf8')))
238-
```
236+
const FastifyApp = require('fastify-app').default;
237+
const { load } = require('js-yaml');
238+
const { readFileSync } = require('fs');
239+
const knex = require('knex');
240+
241+
const config = load(readFileSync('./config.yaml', 'utf8'));
242+
243+
/************************************
244+
* Initialize knex and put it in global
245+
************************************/
246+
if (config.database?.client) {
247+
Object.defineProperty(global, 'knex', {
248+
value: knex({
249+
client: config.database.client,
250+
connection: config.database[config.database.client],
251+
pool: config.database.pool
252+
}),
253+
});
254+
}
255+
256+
FastifyApp(config);
257+
```
258+
259+
### Start the server (ES module)
260+
```javascript
261+
import FastifyApp from 'fastify-app';
262+
import { load } from 'js-yaml';
263+
import { readFileSync } from 'fs';
264+
import knex from 'knex';
265+
266+
const config = load(readFileSync('./config.yaml', 'utf8'));
267+
268+
/************************************
269+
* Initialize knex and put it in global
270+
************************************/
271+
if (config.database?.client) {
272+
Object.defineProperty(global, 'knex', {
273+
value: knex.knex({
274+
client: config.database.client,
275+
connection: config.database[config.database.client],
276+
pool: config.database.pool
277+
}),
278+
});
279+
}
280+
281+
FastifyApp(config);
282+
```
283+
284+
## Breaking changes
285+
286+
### 1.1.0
287+
- The database is no longer initialized. You need to initialize the database connection yourself.
288+
- Route files are no longer limited to `api.js`. Any file that does not start with an underscore and ends with `{.js, .mjs, .ts}` will be registered to the fastify instance.

babel.config.js

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
module.exports = {
2+
presets: [
3+
['@babel/preset-env', {
4+
modules: "commonjs",
5+
}]
6+
]
7+
};

0 commit comments

Comments
 (0)