💨 Breeze
Breeze is a development dashboard for Lucky Framework that helps you to debug and fine-tune your application.
Screenshots
Easy debug logs | View your app requests |
---|---|
Overview of a request | See queries |
---|---|
Create extensions | Preview emails |
---|---|
Installation
- Add the dependency to your
shard.yml
:
dependencies:
breeze:
github: luckyframework/breeze
- Run
shards install
- Add the require to your
src/shards.cr
:
require "avram"
require "lucky"
# ...
# Add this line here
require "breeze"
- Add the tasks to your
tasks.cr
:
# ...
require "./src/app"
require "lucky_task"
# Add this line here
require "breeze/tasks"
#...
LuckyTask::Runner.run
- Add the spec helpers to your
spec/spec_helper.cr
:
require "spec"
require "lucky_flow"
require "../src/app"
# ...
require "breeze/spec_helpers"
require "./setup/**"
- Run
lucky breeze.install
- 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 theAvram::Database
your models inherit from. By default, it'sAppDatabase
.enabled
- When set tofalse
, 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
- Add the require to your
src/shards.cr
right below yourrequire "breeze"
:
require "breeze"
require "breeze/extensions/breeze_carbon"
- 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
- Add the
BreezeCarbon
config toconfig/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
- Create your new extension module (e.g.
module MyBreezeExt
), and addextend Breeze::Extension
- 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
- Create your actions, and pages like a standard Lucky app. Actions inherit from
Breeze::BreezeAction
. Pages inherit fromBreeze::BreezeLayout
. - 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
- Fork it (https://github.com/luckyframework/breeze/fork)
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
Contributors
- Jeremy Woertink - creator and maintainer