Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vdegenne/node-vcms
a tiny node cms (express, objection, express-session/redis, and more)
https://github.com/vdegenne/node-vcms
Last synced: about 1 month ago
JSON representation
a tiny node cms (express, objection, express-session/redis, and more)
- Host: GitHub
- URL: https://github.com/vdegenne/node-vcms
- Owner: vdegenne
- Created: 2018-05-08T15:05:33.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-23T19:55:29.000Z (almost 2 years ago)
- Last Synced: 2024-10-12T14:51:01.775Z (3 months ago)
- Language: TypeScript
- Homepage:
- Size: 417 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/vcms)
A tiny node cms (express, objection, express-session/redis, and more)
## Installation
```bash
yarn add vcms
# or
npm i vcms
```
## Starting a project
create `app.js` (or whichever name you like) :
```javascript
const {start} = require('vcms');
start();
```
That is the minimum code possible for an application using `vcms`. \
You can run this dummy app using : `node app.js`.
This will just start a server on default port `8000` with nothing but a `ping` route :
```bash
curl localhost:8000/ping
```
If this request returns `"pong"` then it means the server has started successfully.
## Adding some routers
So far our application is boring, does nothing but just "ping/pong". \
The next step is to add some routes to our `vcms` application. \
`vcms` organises packs of routes in files also called "routers". \
To demonstrate this type of organisational structure, let's create `greetings.router.js` in the same directory where we created `app.js` and add this content :
```javascript
const {Router} = require('vcms');
const router = Router();
router.get('/hello', async (req, res) => {
res.send('hello world')
});
router.get('/bye', async (req, res) => {
res.send('bye world')
});
module.exports = router;
```
Now we have to tell our application to use this router (which provides 2 routes `/hello` and `/bye`).
Let's create `startupconfig.js` , and write the following :
```javascript
module.exports = (config) => {
config.routers = {
'/greetings': require('./greetings.router');
}
return config;
}
```
It is important that this file is called `startupconfig.js` here (or `startupconfig.ts` for typescript) because the framework will try to find this file in order to init the application. \
There is just few requirements, the script needs to return a function. This function has one argument `config`, and finally the function needs to return this `config` object or an object satisfying the `VcmsOptions` interface. \
Here is an example using ESNext version to make it more clear :
```typescript
import {StartupFunction, VcmsOptions} from 'vcms';
import {greetingsRouter} from './routers/greetings.router';
const startup: StartupFunction = async (config: VcmsOptions) => {
config.database = true;
/**
* config.node_env contains the current NODE_ENV if it was set
* or is equal to 'prod' as a default
*/
switch (config.node_env) {
case 'dev':
config.db_host = 'localhost:5432'; // shorthand
// config.db_host will be 'localhost'
// config.db_port will be 5432
break;
case 'prod':
config.db_host = '1.2.3.4';
config.db_port = 5433;
break;
}
// routers
config.routers = {
'/greetings': greetingsRouter
}
// http2 example
config.http2 = true;
config.http2_cert = process.cwd() + '/server.crt';
config.http2_key = process.cwd() + '/server.key';
return config;
}
export default startup;
```
When we restart our application the routes `/greetings/hello` and `/greetings/bye` should be accessibles. \
Think about the `startupconfig` script as a middleware we can use to rewrite most of application internal configurations.
*The `startupconfig.js` file is the dynamic way to configure the application. Proceed reading the next chapter to see how to configure the application statically.*
## Static Configuration
One particularity of `vcms` is that it has a default state and this state can be customized almost entirely. \
In the previous section we saw how to configure the application dynamically (say the behavior defined with some code). There is also a static way and there are three ways of modifying the state statically :
* using a `.vcms.yml` configuration file.
* [dynamically through the `startupconfig.js` file.]
* using environment variables.
* using command-line arguments.
The precedence is performed in the order of the list above. For instance the command-line `--port` argument will override `port` property in the configuration file, and a configuration overridden in `startupconfig.js` will override properties in the `.vcms.yml` file.
### Using command-line arguments
```bash
# Command-Line Arguments
node app.js --port/-p \
--static \
--local-hostname/-h \
--database/-d [ --db-type \
--db-host \
--db-port \
--db-name \
--db-user
--db-password ] \
--session/-s [ --redis-host ] \
--session-cookie-domain \
--http2 [ --http2-key \
--http2-cert ]
```
All properties are optionals. Between brackets are the properties that are specifics to the property before hand, for instance `--db-type` is only considered by the application if `--database` has been set.
## Configuration options
| Name | Type | Possible values | Default | Description |
|-----------------------|-----------|-----------------------|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Node Environment | `string` | `test`, `dev`, `prod` | `prod` | Only available as an environmental variable. It is used to load environment-specific options from the configuration file (see *"Configuration File"* section). |
| Port | `number` | * | 8000 | Listening port of the application. |
| Public Directory | `string` | * | `public` | Directory containing static files to serve. |
| Local Hostname | `string` | * | `localhost` | Local hostname of the local application. It's recommended to use a hostname when using inter-domain cookies or proxy so informations can be shared between urls and applications. |
| Database | `boolean` | `false`/`true` | `false` | Specify if the database support should be enabled or not. |
| Session | `boolean` | `false`/`true` | `false` | Specify if the session support should be enabled or not. |
| Session Cookie Domain | `string` | * | `localhost` | If the session support is enabled, the main session cookie will use this value as its accessibility scope. |
You also have :
- **DB_TYPE**, **DB_HOST**, **DB_PORT**, **DB_NAME**, **DB_USER**, **DB_PASSWORD** ...when the database support is activated
- **REDIS_HOST** ...when the session support is activated
## Configuration file
We can create a file called `.vcms.yml` (yaml file) at the root of our project.
```yaml
port: 3000
local-hostname: hello.app.local
database: true
db-host: localhost:5432
session: false
prod:
port: 8080
db-host: 1.2.3.4:5433
public-directory: public/build
```
## Environmental Variables Equivalent
```bash
# Environmental Variables Version
NODE_ENV
PORT
PUBLIC_DIRECTORY
LOCAL_HOSTNAME
DATABASE
SESSION
SESSION_COOKIE_DOMAIN
HTTP2_REQUIRED
HTTP2_KEY
HTTP2_CERT
```
## notes
- If you want to know more about this framework, please contact me.
- You can propose some PRs on the related github if you want to contribute to this mini project. I'll be more than willing.