fdocr / kemal-ride

kemal-ride

Shard that helps structure Kemal projects and reduce boilerplate work required before/during/after development.

For now there's a lot of nuance and too many defaults enabled, but it's part of the process. The ethos is to embrace Kemal & Sinatra's essence/simplicity without sacrificing maintainability as a project grows.

Regrets, I've had a few

But then again too few to mention

I did what I had to do

Installation

You'll need Crystal and Yarn installed locally, also Redis & Postgres services available before you get started. You can always disable features you don't want/need.

1. Initialize a new crystal app

crystal init app app_name
cd app_name

2. Add the dependency to your shard.yml:

   dependencies:
     kemal-ride:
       github: fdocr/kemal-ride

3. Run shards install

4. Rename src/app_name.cr file as src/sam.cr and replace the contents with the following code:

require "dotenv"
Dotenv.load

require "sam"
require "kemal-ride"
require "../lib/kemal-ride/src/kemal-ride/sam.cr"

Sam.help

5. Run the following commands to create & initialize the project structure

# Create directory structure, add default files & yarn install
crystal src/sam.cr kemal:ride

# Start your local development server
make sam kemal:dev

Usage

At this point you have a local server that has:

• Sensible Kemal configuration
  • CSRF protection
  • Redis-backed sessions
• ORM
  • Postgres by default using jennifer.cr
• Background jobs
  • Redis backed using mosquito
• Webpack support
  • Tailwindcss for CSS framework
  • StimulusJS for minimal JS framework
• Email support
  • Using carbon
• OpenTelemetry support
  • Using jgaskins/opentelemetry
• view macro
  • Helps render views using layout convention
• sam.cr tasks for ease of development
  • Some of them below
• Authentication model (User class) with handlers and views
  • Not very customizable at the moment but a nice kickstart
• Policy classes and helpers to enforce them from route handlers

# Start local development environment
make sam kemal:dev

# Generate User class, `/auth/*` route handlers + views
# Strongly recommended to make this the first migration on your project
make sam kemal:auth

# Run specs
make sam kemal:test

# Jennifer.cr tasks are included. Read more about them:
# https://imdrasil.github.io/jennifer.cr/docs/command_line
make sam db:drop
make sam db:create
make sam db:migrate
make sam db:setup
make sam generate:model
make sam generate:migration
etc...

Development

TODO: Write development instructions here

Contributing

1. Fork it (https://github.com/fdocr/kemal-ride/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Fernando Valverde - creator and maintainer