UNPKG

9.26 kBMarkdownView Raw
1# Avian
2
3Create Enterprise-class component driven applications that scale.
4
5[![CircleCI](https://img.shields.io/circleci/build/github/flypapertech/avian/master)](https://circleci.com/gh/flypapertech/avian/tree/master)
6[![Docker Cloud Build Status](https://img.shields.io/docker/cloud/build/flypapertech/avian)](https://hub.docker.com/repository/docker/flypapertech/avian/builds)
7[![Known Vulnerabilities](https://snyk.io/test/github/flypapertech/avian/badge.svg)](https://snyk.io/test/github/flypapertech/avian)
8[![npm (scoped)](https://img.shields.io/npm/v/@flypapertech/avian.svg)](https://www.npmjs.com/package/@flypapertech/avian)
9[![License](https://img.shields.io/npm/l/@flypapertech/avian.svg)](https://github.com/flypapertech/avian/blob/master/LICENSE)
10[![Dependencies](https://david-dm.org/flypapertech/avian/status.svg)](https://david-dm.org/flypapertech/avian)
11[![Docker Pulls](https://img.shields.io/docker/pulls/flypapertech/avian)](https://hub.docker.com/r/flypapertech/avian)
12
13## Synopsis
14
15Avian is an application server based on years of experience, built on [Express](https://github.com/expressjs/express) and [Redis](https://redislabs.com/) that meets infinitely scalable demands.
16
17## Key Features
18
19- Multi-core / Multi-threaded application host operations remove the burden of load balancing across cpu cores.
20- Out of the box webpacking with sane defaults. Don't worry you can override and/or add to them whenever you want :)
21- A unique and easy to use component-based model that is flexible with popular frameworks such as Angular, Vue.js, ReactJS.
22- Supports popular view templating engines such as Pug, EJS, Handlebars and plain HTML.
23- Supports Pino, Bunyan, and Fluentd logging frameworks.
24
25## Installation
26
27### NPM
28
29The latest stable release of Avian is available on [npmjs.com](https://www.npmjs.com/package/@flypapertech/avian).
30
31The most common scenario is to install Avian as a dependency of your project.
32
33 npm install @flypapertech/avian
34
35 or
36
37 yarn add @flypapertech/avian
38
39And can be accessed as...
40
41 node ./node_modules/.bin/avian
42
43Alternatively, Avian can be installed globally, making it possible to serve multiple applications with a single installation of Avian.
44
45 npm install @flypapertech/avian -g
46
47 or
48
49 yarn global add @flypapertech/avian
50
51And can be accessed globally, but will need to be told where your Avian application is located...
52
53 avian --home /path/to/avian/app/home
54
55### System Requirements
56
57#### NodeJS
58
59Avian requires NodeJS version 8.0 and above.
60
61#### Redis Server
62
63Avian uses Redis Server for storing session data, caching component config object requests and arbitrary caching requirements you may have.
64
65Suggested Redis Installation Methods
66
67##### macOS
68`brew install redis`
69##### Ubuntu Linux
70`apt install redis-server`
71##### Alpine Linux
72`apk add redis`
73##### Windows (experimental)
74 - [Windows with WSL (10 and higher)](https://redislabs.com/blog/redis-on-windows-10/)
75 - [Windows without WSL (8.1 and lower)](https://redislabs.com/blog/redis-on-windows-8-1-and-previous-versions/)
76 - Note: It is not recommended to use Redis in production on Windows with out WSL.
77
78## Getting Started
79
80### CLI Arguments
81
82 Options:
83 --help Show help [boolean]
84 --version Show version number [boolean]
85 --name, -n The name of your application[default: "localhost"]
86 --home, -h The directory of your application.
87 [default: current working directory]
88 --mode, -m Deployment mode to run Avian in.
89 [choices: "development", "production"] [default: "development"]
90 --port, -p Which port to serve your application on.
91 [default: 8080]
92 --defaultComponent, --dc The point of entry to your application.
93 [default: "index"]
94 --spa Start Avian in a single-page-application
95 configuration. [boolean] [default: false]
96 --bundleSkip [boolean] [default: false]
97 --bundleOnly [boolean] [default: false]
98 --redisHost [default: "127.0.0.1"]
99 --redisPort [default: 6379]
100 --redisPass [default: undefined]
101 --redisSessionDB [default: 1]
102 --redisCacheDB [default: 2]
103 --redisCronSchedulerDB [default: 3]
104 --webpackHome [default: undefined]
105 --logger, -l Which logging framework to use.
106 [choices: "pino", "bunyan", "fluent"]
107 --loggerFluentLabel, --lfl [default: "debug"]
108 --loggerFluentTag, --lft [default: "debug"]
109 --loggerFluentHost, --lfh [default: "127.0.0.1"]
110 --loggerFluentPort, --lfp [default: 24224]
111 --sslCert [string]
112 --sslKey [string]
113 --cronJobScheduler, --cjs Avian components are capable of scheduling
114 cron-like jobs that are executed on the server.
115 [boolean] [default: false]
116 --compression Use express-compression [boolean] [default: false]
117
118### Application Folder Structure
119
120 ├── assets [optional, statically served at /assets]
121 ├── static [optional, statically served at /static]
122 ├── cache [auto-generated by Avian in production mode to hold cached files]
123 ├── components
124 │ ├── avian.service.(ts/js) [optional, used to add service routes to / path]
125 │ ├── component_name.client.(ts/js) [optional, contains all JavaScript/TypeScript logic for a component. Will be bundled with Webpack]
126 │ ├── component_name.view.(pug/ejs/html) [optional, renders output to a screen, e.g. a /component_name get request]
127 │ ├── component_name.service.(ts/js) [optional, used to add service routes to /component_name]
128 │ ├── component_name.config.json [optional, served at /component_name/config/objects.json and passed to view files at render time]
129 │ ├── component_name [components can be in a flat folder or scaffolded like this]
130 │ │ ├── component_name.client.(ts/js)
131 │ │ ├── component_name.view.(pug/ejs/html)
132 │ │ ├── component_name.service.(ts/js)
133 │ │ ├── component_name.config.json
134 ├── logs [auto-generated by Avian in production mode]
135 ├── package.json
136 ├── private [auto-generated by Avian to contain server side compiled files, e.g. component service files]
137 ├── public [auto-generated, for compiled component bundles, statically served at /]
138
139### Session Management
140
141Avian uses [express-session](https://github.com/expressjs/session) to manage client sessions. All sessions are stored in a Redis store.
142
143- Browser Based Clients
144 - Avian uses secure [HttpOnly Cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#Secure_and_HttpOnly_cookies) for managing browser based client sessions.
145
146- Mobile Device and API Clients
147 - Avian augments express-session to allow API and mobile device sessions management. Since those clients may not use coookies they simply need to send their session ID in the authorization header of all requests made to Avian. See below for an example header.
148
149```json
150headers: {
151 Authorization: "Bearer Session_ID"
152}
153```
154
155### Global Variables Added by Avian
156
157#### Properties Added to All Request Objects
158
159`req.argv` contains a copy of all arguments passed to Avian at start time.
160
161`req.cache` is a RedisClient instance hooked to Avian's config object cache. Feel free to use it for your own needs as well.
162
163`req.params` paramaters passed to your component. Typically this is used to determine the component name being rendered, e.g. req.params.component.
164
165`req.query` contains all query parameters passed to the componenent being requested.
166
167#### Developing w/ TypeScript
168
169To make TypeScript aware of the globals Avian adds to your application simply place the below import into any .d.ts file that is within your application.
170
171```typescript
172import * as Avian from "@flypapertech/avian"
173```
174
175## Examples
176
177Examples are located in the [examples directory](https://github.com/flypapertech/avian/tree/master/examples).
178
179## Contributors
180
181 Dan Stephenson
182 Nick Fredricks
183
184## License
185
186 MIT
187
188## Copyright
189
190 2018 - 2020 FlyPaper Technologies, LLC
191 2016 - 2018 Thoughtpivot, LLC