💨 Breeze

Breeze is a development dashboard for Lucky Framework that helps you to debug and fine-tune your application.

Screenshots

Installation

1. Add the dependency to your shard.yml:

dependencies:
  breeze:
    github: luckyframework/breeze

2. Run shards install
3. Add the require to your src/shards.cr:

require "avram"
require "lucky"
# ...
# Add this line here
require "breeze"

4. Add the tasks to your tasks.cr:

# ...
require "./src/app"
require "lucky_task"

# Add this line here
require "breeze/tasks"

#...
LuckyTask::Runner.run

5. Add the spec helpers to your spec/spec_helper.cr:

require "spec"
require "lucky_flow"
require "../src/app"
# ...
require "breeze/spec_helpers"

require "./setup/**"

6. Run lucky breeze.install
7. Run lucky db.migrate

Usage

Boot your app locally (lucky dev), then open your app in the browser and start using your app. When you're ready to check out Breeze, look at your development log. You'll see logs similar to this:

▸ Debug at http://localhost:5000/breeze/requests/6

You can visit a specific request, or just go to /breeze/requests to browse.

Configuration

You breeze configuration will be located in config/breeze.cr. This file was added for you when you ran lucky breeze.install.

# config/breeze.cr

Breeze.configure do |settings|
  # The database to store the request info
  settings.database = AppDatabase

  # Enable Breeze only for this environment
  settings.enabled = LuckyEnv.development?
end

# Configuration settings for Actions
Breeze::ActionHelpers.configure do |settings|
  # This setting is optional
  settings.skip_pipes_if = ->(context : HTTP::Server::Context) {
    context.request.resource.starts_with?("/admin")
  }
end

• database - This is the Avram::Database your models inherit from. By default, it's AppDatabase.
• enabled - When set to false, you won't be able to visit any of the breeze pages. This is enabled for development by default.
• skip_pipes_if - Breeze will store the request and response for every action in your app. If there's some actions you don't want to store, you can skip these by matching the request path or resource. You could also skip certain content types, or whatever else you want.

Breeze Extensions

Breeze comes with a Carbon extension that allows you to preview your emails right in the browser.

If you develop a Breeze extension, let us know and we will list it here!

Installing BreezeCarbon

1. Add the require to your src/shards.cr right below your require "breeze":

require "breeze"
require "breeze/extensions/breeze_carbon"

2. Add your Email preview class to src/emails/previews.cr:

class Emails::Previews < Carbon::EmailPreviews
  def previews : Array(Carbon::Email)
    [
      WelcomeEmail.new(UserQuery.first),
      PasswordResetRequestEmail.new(UserQuery.first),
    ] of Carbon::Email
  end
end

3. Add the BreezeCarbon config to config/breeze.cr:

BreezeCarbon.configure do |settings|

  # Set this to the name of your preview class
  settings.email_previews = Emails::Previews
end
Breeze.register BreezeCarbon

Using BreezeCarbon

Just visit /breeze/emails in your browser, and you'll see your emails. Click the HTML button to see the HTML version of your email, or the TEXT to see the plain text version.

Configuring BreezeCarbon

BreezeCarbon requires setting the email_previews setting to the name of your email preview class. Your email preview class should inherit from Carbon::EmailPreviews, and define an instance method previews which returns an Array(Carbon::Email).

Extending Breeze

1. Create your new extension module (e.g. module MyBreezeExt), and add extend Breeze::Extension
2. Define your navbar link method in your module:

def self.navbar_link : Breeze::NavbarLink
  Breeze::NavbarLink.new(
    link_text: "Breeze Ext",
    link_to: MyBreezeExt::Index.path
  )
end

3. Create your actions, and pages like a standard Lucky app. Actions inherit from Breeze::BreezeAction. Pages inherit from Breeze::BreezeLayout.
4. Lucky apps that include Breeze and your extension will need to add Breeze.register MyBreezeExt.

For more examples on creating a Breeze extension, look at the BreezeCarbon extension in src/extensions/breeze_carbon.cr

Development

Install shards shards install, and start making changes. Be sure to run ameba, and the crystal formatter crystal tool format spec src.

Read through the issues for things you can work on. If you have an idea, feel free to open a new issue!

Contributing

1. Fork it (https://github.com/luckyframework/breeze/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

• Jeremy Woertink - creator and maintainer