onyx
Onyx
Macros for easier development.
Supporters ❤️
Thanks to all my patrons, I can continue working on beautiful Open Source Software! 🙏
Alexander Maslov, Lauri Jutila
You can become a patron too in exchange of prioritized support and other perks
About 👋
This shard (should be called Onyx/Onyx) includes a number of convenient macros for easier day-to-day development with the Onyx Framework. It convers almost all of its components:
- Top-level macros:
- Onyx::HTTP macros for use with Onyx::HTTP
- Onyx::REST macros for use with Onyx::REST
- Onyx::SQL macros for use with Onyx::SQL
Installation 📥
Add this to your application's shard.yml
:
dependencies:
onyx:
github: onyxframework/onyx
version: ~> 0.1.2
This shard follows Semantic Versioning v2.0.0, so check releases and change the version
accordingly. Please visit github.com/crystal-lang/shards to know more about Crystal shards.
Note that this shard does not have implicit dependencies for other framework components. For example, to use "onyx/http"
macros, you must add onyx-http
dependendency as well:
dependencies:
onyx:
github: onyxframework/onyx
version: ~> 0.1.0
onyx-http:
github: onyxframework/http
version: ~> 0.1.0
Usage 💻
Env
Firstly sets CRYSTAL_ENV
environment variable to "development"
if not set yet. Then loads other environment variables from .env
files in this order, overwriting if defined multiple times:
.env
file.env.local
file.env.#{CRYSTAL_ENV}
file.env.#{CRYSTAL_ENV}.local
file
It also enables .runtime_env
and .buildtime_env
top-level macros which raise if an environment variable is not defined.
require "onyx/env"
# At this point, all variables are loaded from .env files
#
runtime_env DATABASE_URL # Will raise on program start if DATABASE_URL variable is missing
This feature is powered by dotenv shard by @gdotdesign.
Logger
Enables using the singleton Onyx.logger
instance.
require "onyx/logger"
Onyx.logger.info("Hello world!")
DEBUG [12:45:52.520 #13543] Hello world!
DB
Enables using the singleton Onyx.db
instance. It raises if no DATABASE_URL
environment variable is defined or the database is not reachable.
require "onyx/db"
Onyx.db.query("SELECT 1")
HTTP
Enables the singleton Onyx::HTTP instance. It automatically requires Logger and adds the following methods:
Onyx.get
,Onyx.post
,Onyx.put
,Onyx.patch
,Onyx.delete
andOnyx.options
which call the accordingOnyx::HTTP::Router
methodOnyx.draw
which callsOnyx::HTTP::Router#draw
Onyx.listen
which launches theOnyx::HTTP::Server
instance
Example:
require "onyx/http"
Onyx.get "/" do |env|
env.response << "Hello Onyx"
end
Onyx.listen
> curl http://localhost:5000
Hello Onyx
You must manually add Onyx::HTTP as a dependency in your shard.yml
.
REST
Enables the singleton Onyx::HTTP instance. It automatically requires HTTP and adds Onyx.render
and Onyx.renderer
methods:
require "onyx/rest"
struct MyView
include Onyx::REST::View
def initialize(@foo : String)
end
text("foo = #{@foo}")
end
Onyx.render(:text)
# Equals to
Onyx.renderer = Onyx::REST::Renderers::Text.new
Onyx.get "/" do |env|
env.response.view = MyView.new("bar")
end
Onyx.listen
You must manually add Onyx::REST as a dependency in your shard.yml
.
SQL
Enables the singleton Onyx::SQL Repository
instance accessible with Onyx.repo
method and also adds proxy Onyx.query
, Onyx.exec
and Onyx.repo
methods. It automatically requires Env and DB (meaning that you must have DATABASE_URL
variable defined).
require "onyx/sql"
class User
include Onyx::SQL::Model
schema users do
pkey id : Int32
type name : String
end
end
users = Onyx.query(User.where(id: 42)).first?
Community 🍪
There are multiple places to talk about this particular shard and about other ones as well:
- Main Onyx Gitter chat
- Onyx Framework Gitter community
- Vlad Faust Gitter community
- Onyx Framework Twitter
- Onyx Framework Telegram channel
Support ❤️
This shard is maintained by me, Vlad Faust, a passionate developer with years of programming and product experience. I love creating Open-Source and I want to be able to work full-time on Open-Source projects.
I will do my best to answer your questions in the free communication channels above, but if you want prioritized support, then please consider becoming my patron. Your issues will be labeled with your patronage status, and if you have a sponsor tier, then you and your team be able to communicate with me in private or semi-private channels such as e-mail and Twist. There are other perks to consider, so please, don't hesistate to check my Patreon page:
You could also help me a lot if you leave a star to this GitHub repository and spread the world about Crystal and Onyx! 📣
Contributing
- Fork it ( https://github.com/onyxframework/http/fork )
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'feat: some feature') using Angular style commits
- Push to the branch (git push origin my-new-feature)
- Create a new Pull Request
Contributors
- Vlad Faust - creator and maintainer
Licensing
This software is licensed under MIT License.