Overview of Lucky
- Overview of Lucky
- Installing Lucky
- Configuring Your Application
- Setting Up & Migrating the Database
- Actions and Routing
- Rendering HTML Pages
- Models and Querying the Database
- Custom Queries
- Saving Data with Forms
- Asset Handling
- Tasks in Lucky
- Logging and Error Handling
- Writing JSON APIs
- Generating Test Data with Boxes
- Browser Tests with LuckyFlow
- Sending Emails with Carbon
- Deploying Lucky with Heroku
The Lucky philosophy
Lucky was designed to solve a few core problems that teams often see. Lucky strives to:
- Catch bugs at compile time, rather than finding them in production.
- Spend less time writing tests, because the compiler catches many errors for you.
- Minimize guesswork with conventions for the most common types of objects.
- Help developers break things into discrete pieces so things are easy to share and maintain in the future.
- Minimize boilerplate code so it’s easy to focus on what your app does better than everyone else.
We do that by using Crystal’s type system to the fullest. You won’t see strings or symbols passed around. Instead you’ll see method calls with types that make sure bugs are caught early.
We have conventions that help you break your app into smaller pieces that are easier to understand. Things like single class per action, and form objects.
We have helpful code generation so that you don’t need to repeat boilerplate.
Lucky was designed for developers that love making reliable products. We think you’ll love it.
File structure overview
A new Lucky app is a slightly modified version of a Crystal app.
The src folder holds most of your application code. This includes actions for handling requests, queries for database access, pages for rendering HTML, and a few other things.
Here are all the files for configuring your application. A new app comes with a few configuration files, but you can add more as you see fit.
This folder houses all the database migrations for your app.
You can put custom tasks here that can be run by the
lucky command line tool. See
lucky -h for a list of the current tasks.
Place any files you wish to be public in here. For compiled assets, the asset compiler will move the files in to here for you.
This folder contains a setup script for bootstrapping your app by default. Place any other bash style scripts or executables you may need for your app in here.
The test files for your application will go in to this folder.
Procfile.dev is used when you run
lucky dev. By default there is a web and an assets process that are started. You can add more if you need them.
Procfile is often used in production. Companies like Heroku, use it to determine how it should run the app.
It’s standard convention for Crystal applications to place the main business logic in to this folder, so there’s a lot that is going on here.
This is where classes go that handle incoming web requests.
Action mixins are modules that you can include in actions. Great for authentication, authorization, setting up finders or ensuring certain headers are set.
These are shared view components like displaying flash messages, errors, and default layout components like the head tags.
Place your styles in here. By default, Lucky uses SASS, but you can configure for any preprocessor.
The classes used by Carbon along with the email templates are placed in here.
Forms for saving database records or interacting with HTTP forms.
Put anything that models your business. Database objects go here, but you could also put things like service objects.
Pages used for rendering HTML in response to web requests.
This is where your database queries go.
This is more common with APIs. These are the files that transform your structured data in to some format like json or xml.
This requires all the files and folders that your app needs to run. It includes your middleware stack. Add your custom HTTP::Handlers to the
middleware method array.
Require your third party dependencies (shards) here.
This file requires the app and starts an HTTP server.
Adding custom files and folders
The structure in Lucky is to create a folder for like objects/modules, etc… You may find yourself adding things like service objects, custom http handlers, mutations, or maybe even other asset files like images for preprocessing. For each of these, just create a new folder in
src/ and be sure to add the require in your
e.g. Creating a
src/handlers/http_basic_auth_handler.cr, be sure to add
require "./handlers/**" to