luckyframework / lucky

A full-featured Crystal web framework that catches bugs for you, runs incredibly fast, and helps you write code that lasts.

The goal: prevent bugs, forget about most performance issues, and spend more time on code instead of debugging and fixing tests.

In summary, make writing stunning web applications fast, fun, and easy.

Coming from Rails?

• Ruby on Rails to Lucky on Crystal: Blazing fast, fewer bugs, and even more fun.

Try Lucky

Lucky has a fresh new set of guides that make it easy to get started.

Feel free to say hi or ask questions on our chat room.

Or you can copy a real working app with Lucky JumpStart.

Installing Lucky

To install Lucky, read the Installing Lucky guides for your Operating System. The guide will walk you through installing a command-line utility used for generating new Lucky applications.

Keep up-to-date

Keep up to date by following @luckyframework on Twitter.

Documentation

API (main)

What's it look like?

JSON endpoint:

class Api::Users::Show < ApiAction
  get "/api/users/:user_id" do
    user = UserQuery.find(user_id)
    json UserSerializer.new(user)
  end
end

• If you want you can set up custom routes like get "/sign_in" for non REST routes.
• A user_id method is generated because there is a user_id route parameter.
• Use json to render JSON. Extract serializers for reusable JSON responses.

Database models

# Set up the model
class User < BaseModel
  table do
    column last_active_at : Time
    column last_name : String
    column nickname : String?
  end
end

• Sets up the columns that you’d like to use, along with their types
• You can add ? to the type when the column can be nil . Crystal will then help you remember not to call methods on it that won't work.
• Lucky will set up presence validations for required fields (last_active_at and last_name since they are not marked as nilable).

Querying the database

# Add some methods to help query the database
class UserQuery < User::BaseQuery
  def recently_active
    last_active_at.gt(1.week.ago)
  end

  def sorted_by_last_name
    last_name.lower.desc_order
  end
end

# Query the database
UserQuery.new.recently_active.sorted_by_last_name

• User::BaseQuery is automatically generated when you define a model. Inherit from it to customize queries.
• Set up named scopes with instance methods.
• Lucky sets up methods for all the columns so that if you mistype a column name it will tell you at compile-time.
• Use the lower method on a String column to make sure Postgres sorts everything in lowercase.
• Use gt to get users last active greater than 1 week ago. Lucky has lots of powerful abstractions for creating complex queries, and type specific methods (like lower).

Rendering HTML:

class Users::Index < BrowserAction
  get "/users" do
    users = UserQuery.new.sorted_by_last_name
    render IndexPage, users: users
  end
end

class Users::IndexPage < MainLayout
  needs users : UserQuery

  def content
    render_new_user_button
    render_user_list
  end

  private def render_new_user_button
    link "New User", to: Users::New
  end

  private def render_user_list
    ul class: "user-list" do
      users.each do |user|
        li do
          link user.name, to: Users::Show.with(user.id)
          text " - "
          text user.nickname || "No Nickname"
        end
      end
    end
  end
end

• needs users : UserQuery tells the compiler that it must be passed users of the type UserQuery.
• If you forget to pass something that a page needs, it will let you know at compile time. Fewer bugs and faster debugging.
• Write tags with Crystal methods. Tags are automatically closed and whitespace is removed.
• Easily extract named methods since pages are made of regular classes and methods. This makes your HTML pages incredibly easy to read.
• Link to other pages with ease. Just use the action name: Users::New. Pass params using with: Users::Show.with(user.id). No more trying to remember path helpers and whether the helper is pluralized or not - If you forget to pass a param to a route, Lucky will let you know at compile-time.
• Since we defined column nickname : String? as nilable, Lucky would fail to compile the page if you just did text user.nickname since it disallows printing nil. So instead we add a fallback "No Nickname". No more accidentally printing empty text in HTML!

Testing

You need to make sure to install the Crystal dependencies.

1. Run shards install
2. Run crystal spec from the project root.

Contributing

See CONTRIBUTING.md

Lucky to have you!

We love all of the community members that have put in hard work to make Lucky better. If you're one of those people, we want to give you a t-shirt!

To get a shirt, we ask that you have made a significant contribution to Lucky. This includes things like submitting PRs with bug fixes and feature implementations, helping other members work through problems, and deploying real world applications using Lucky!

To claim your shirt, fill in this form.

Contributors

• paulcsmith Paul Smith - creator, maintainer
• Our wonderful community - ❤️

Thanks & attributions

• SessionHandler, CookieHandler and FlashHandler are based on Amber. Thank you to the Amber team!
• Thanks to Rails for inspiring many of the ideas that are easy to take for granted. Convention over configuration, removing boilerplate, and most importantly - focusing on developer happiness.
• Thanks to Phoenix, Ecto and Elixir for inspiring Avram's save operations, Lucky's single base actions and pipes, and focusing on helpful error messages.
• lucky watch based heavily on Sentry. Thanks @samueleaton!

lucky's Issues

Add spec helpers

For request specs

Something I've actually used (also includes FactoryBot like factories):
https://gist.github.com/paulcsmith/c5da6e8888d1a50f13fb6d9acc37a6a9

Some experimental ideas:
https://gist.github.com/paulcsmith/d44ac002bd1b7c57dcb8f7217ac499a7

Pages don't need much to get started

html = MyCoolPage.new(whatever_args).render

html.to_s.should contain("some text")

Silence asset helper macro

Include what Lucky isn't for and what was deprioritized

Be honest. Help people make good technical decisions

https://blog.bradfieldcs.com/you-are-not-google-84912cf44afb

Allow passing a custom page to `render`

class Tasks::Create
  action do
    render Users::SomePage
  end
end

Add link helpers

Add nested resources

Allow inferring page namespace

class Tasks::Create
  action do
    render NewPage # Renders Tasks::NewPage
  end
end

Add lucky dev task - starts server and web pack dev server

Add check box helper

Remember to use hidden field so we get the unchecked value. This will work similar to the text_input helpers https://github.com/luckyframework/web/blob/master/src/lucky_web/tags/input_helpers.cr

http://stackoverflow.com/questions/11550941/why-does-the-check-box-form-helper-generate-two-checkboxes-one-hidden

Also: https://github.com/plataformatec/simple_form/blob/master/lib/simple_form/inputs/boolean_input.rb#L93

Infer routes with `action` macro

Add ability to render pages in layouts

Ikagi

The Lucky philosophy is to try to be at the intersection of happiness, usefulness, ease of use, what you can get paid for, and what is fulfilling. A framework with as few tradeoffs as possible.

Dasherize HTML attributes

data_confirm -> data-confirm

Don't use JWT for session cookies

https://kev.inburke.com/kevin/things-to-use-instead-of-jwt/

Add expose

Pass assigns to views

render user: UserRows.first

Fix bug where root route/path is ""

HTML escape HTML attributes

Make assign more robust

If you have the same assign in multiple pages it duplicates it the asking. That needs to be fixed

Add HerokuDeploy task

So it can be inherited from in the default lucky deploy task, but can be overridden if you want to implement your own task

HTML escape text

Add lucky watch task

watches files and restarts server

Don't set up `getters` for assigns

Make it clear what's coming from assigns, also less likely to have collisions with existing methods this way

Make sure macro `finished` runs when using with a server

Sometimes macro finished doesn't work as expected when you use a server. Test this out to make sure things work correctly

https://github.com/luckyframework/web/blob/master/src/lucky_web/html_view.cr#L25

Add rails-ujs

Don't include method in route task output

Add form helpers

Expose and memoize in one go

expose :users, UserQuery.all, memoize_as: UserQuery

# or
expose_memoized users : UserQuery, UserQuery.all

Use git-crypt for storing and reading secrets

https://www.agwa.name/projects/git-crypt/ Transparent file encryption. Can use symmetric keys so devs can easily share it, or use GPG.

Add some lucky tasks to get it working well, make it easy to publish the key to Heroku on setup

lucky secrets.encrypt_file # Add file(s) to .git-attributes
lucky secrets.sync_key prod # Pushes the key as an env var on Heroku

• http://www.twinbit.it/en/blog/storing-sensitive-data-git-repository-using-git-crypt
• https://news.ycombinator.com/item?id=7508734

Add tests for multiple assigns

Add ability to respond to different formats

Some proof of concept code: https://gist.github.com/paulcsmith/b26cfcaf82c4ff87e9dcc46f6c42e48b

Add namespaces routes

Discuss: Add `don't_escape` to strings and don't escape HTML if it is true

Or maybe the raw helper is already enough?

Make it easier to inherit exposures and assigns

Maybe using methods on the type https://crystal-lang.org/api/0.22.0/Crystal/Macros/TypeNode.html#ancestors%3ACrystal%3A%3AMacros%3A%3AArrayLiteral%28TypeNode%29-instance-method

Add test helpers for testing pages

Possibly use https://github.com/kostya/modest and make some nice matchers

session.should have_content "My App", css: ".main-header"

Add Charms for common utility methods

Generate route helpers automatically

Add redirect methods

Add "Support" section

I really like the one here: https://github.com/wp-cli/wp-cli#support

Add input tag

Add helper for rendering in a layout

class InnerPage < BaseView
  layout BaseLayout # This would probably go in the BaseView

  def inner
    # The inner page
  end

  def title
    "A great title"
  end
end

class BaseLayout < BaseLayout
  @page : BaseView

  def render
    title @page.title
    main do
      # Consider forwarding missing to @page so you can use it's helpers more easily
      @page.inner
    end
  end
end

Instead of this old way

class InnerPage < LuckyWeb::HTMLView
  def render
    Layout.new(self).render.to_s
  end

  def title
    "A great title"
  end
end

class Layout < LuckyWeb::HTMLView
  @page : InnerPage

  def initialize(@page)
    @io = IO::Memory.new
  end

  def render
    title @page.title
  end
end

Show "did you mean?" when an asset doesn't exist

Parse web pack manifest and create asset helper module

Webpack should keep directory structure

https://github.com/webpack-contrib/file-loader#filename-templates

Logo

Add param parser

Rename HTMLView to Page

Add memoize macro

macro memoize(type_decl)
  @{{type_decl.var}} : {{type_decl.type}}?
  def {{type_decl.var}}
    @{{type_decl.var}} ||= {{yield}}
  end
end

class Users::Index < BaseAction
  memoize users : UserQuery do
    UserQuery.all.active
  end
end

https://play.crystal-lang.org/#/r/25hp
Also an interesting version here https://play.crystal-lang.org/#/r/25ha

Discuss: Add optional template rendering to pages

class Users::IndexPage < MainLayout
  needs users : UserQuery

  render_template # Assumes ./index_template.ecr/.slang - Use kilt to support just about anything
  
  # or specify template
  render_template "./some_other_extension.rss.ecr
end

The default would still be to use the HTML tag methods, but sometimes it's much nicer to use templating languages like ECR when doing content heavy pages like landing pages, pricing pages, etc. They're usually quite simple and have large paragraphs of text, which work better in template languages

Add raise_typeof helper

I want to make it easy for beginners to figure out the types of things. This will be helpful when using assigns in Pages, or really for anytime you need a type

macro show_typeof(var)
  raise "Type of `{{var.id}}` is: #{typeof({{var}})}"
end

number = 1
show_typeof(number)