Tutorial: Quick Start

Flitter is a concise, lightweight web app framework based on Express.js. If you have worked with MVC style frameworks before, getting started with Flitter will be pretty straightforward for you. Here are the basics:

1. Create Your App

git clone https://code.garrettmills.dev/flitter/flitter <project folder>

2. Install Dependencies

Flitter packages are managed with Yarn, not NPM:

cd <project folder>
yarn install

3. Set the Environment Config

cp example.env .env
vim .env

4. Add a New Route

Edit the app/routing/routers/index.routes.js file and add a new route to the get section:

// app/routing/routers/index.routes.js
const index = {

    prefix: '/',

    middleware: [],

    get: {
        '/': [ 'controller::Home.welcome' ],

        // Add a route here:
        '/hello_world': [ 'controller::Home.hello_world' ],
    },

    post: {

    },
}

module.exports = exports = index

5. Create the Controller Method

Edit the app/controllers/Home.controller.js file and add the hello_world method:

const Controller = require('libflitter/controller/Controller')

class Home extends Controller {

    welcome(req, res){
        return res.page('welcome')
    }

    // Create the method here
    hello_world(req, res) {
    	// Send a hello message:
    	return res.send('Hello, World!')
    }
}

module.exports = Home

6. Create a New Model

Let's create a model to track individual page-views:

./flitter new model log:PageView

Edit the app/models/log/PageView.model.js file:

const Model = require('flitter-orm/src/model/Model')

class PageView extends Model {
    static get schema() {
        return {
            date: { type: Date, default: () => new Date },
            route_path: String,
        }
    }
}

module.exports = exports = PageView

Here, we added a date field, which defaults to the create time, and a route_path value to the model's schema.

7. Create a New Middleware

Let's create a middleware to log the page views into the database:

./flitter new middleware log:PageView

Edit the app/routing/middleware/log/PageView.middleware.js file that was created to log the page views:

const Middleware = require('libflitter/middleware/Middleware')

class PageView extends Middleware {
    static get services() {
    	// Request the models service to be injected.
        return [...super.services, 'models']
    }

    async test(req, res, next, args = {}){
    	// Get the PageView model CLASS from the models service.
        const PageView = this.models.get('log:PageView')

        const page_view = new PageView({ route_path: req.path })
        await page_view.save()

        // Allow the request to continue.
        next()
    }
}

module.exports = exports = PageView

8. Apply the Middleware Globally

Now, let's register our PageView logging middleware to run on every route Flitter processes.

Edit the app/routing/Middleware.js file to include the middleware's canonical name. This file contains the global middleware applied to all routes:

const Middleware = [    
    'log:PageView',
]

module.exports = exports = Middleware

9. Start the Server

node index.js

Now, if you navigate to the /hello_world route we created, you should see the "Hello, World!" message.

10. Use the Flitter Shell

Now, we can use the Flitter shell to look for the PageView records that were logged:

node --experimental-repl-await flitter shell

(flitter) ➤ PageView = _services.models.get('log:PageView')
[Function: PageView] { collection: 'log_PageView' }
(flitter) ➤ await PageView.findOne()
PageView {
  date: 2020-01-30T20:00:34.409Z,
  route_path: '/hello_world',
  _id: 5e3335e21ce35b1f23e7744b
}
(flitter) ➤ 

For more in-depth overviews of the concepts involved in Flitter, check out the Getting Started series.