Shard Detail

amber v0.2.3

A Crystal web framework that makes building applications fast, simple, and enjoyable. Get started with quick prototyping, less bugs, and blazing fast performance.
crystal web cohesive efficient fast framework amber amber-framework scaffolding cli web-framework

Install & Use

Add the following code to your project's shard.yml under:

dependencies to use in production
- OR -
development_dependencies to use in development


amber:
  github: amberframework/amber
  version: 0.2.3

Readme

Amber Crystal Framework

Gitter Travis license GitHub tag Awesome

Welcome to Amber

Amber is a web application framework written in Crystal inspired by Kemal, Rails, Phoenix and other popular application frameworks.

The purpose of Amber is not to create yet another framework, but to take advantage of the beautiful Crystal language capabilities and provide engineers an efficient, cohesive, and well maintained web framework for the crystal community that embraces the language philosophies, conventions, and guides.

Amber Crystal borrows concepts that already have been battle tested, successful, and embrace new concepts through team and community collaboration and analysis, that aligns with Crystal philosophies.

Read the Docs

Documentation https://docs.ambercr.io

Benchmark

Latest Results 968,824.35 requests per second: 32 cores at 2.7Ghz

ubuntu@ip-172-31-0-70:~/bench⟫ wrk -d 60 -t 20 -c 1015 http://localhost:3000
Running 1m test @ http://localhost:3000
  20 threads and 1015 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     1.86ms    2.88ms  56.61ms   87.54%
    Req/Sec    48.73k     6.01k   88.40k    68.28%
  58225168 requests in 1.00m, 4.01GB read
Requests/sec: 968824.35
Transfer/sec:     68.37MB

Disclaimer: We share these benchmark results with the understanding they may vary depending on configurations and environment settings and by no means we are making any comparison claims with other web application frameworks.

Installation

Linux

Ensure you have the necessary dependencies:

For Debian & Ubuntu
  • These are necessary to compile the CLI:
  • sudo apt-get install build-essential libreadline-dev libsqlite3-dev libpq-dev libmysqlclient-dev libssl-dev

Once you have these dependencies, You can build the amber tool from source:

$ git clone git@github.com:amber-crystal/amber.git
$ cd amber/
$ shards install
$ sudo make
For ArchLinux & derivates
  • Install the CLI from AUR package. Dependencies are automatically installed.
  • yaourt -S amber

You should now be able to run amber in the command line.

Mac OS X

Best way to get amber on Mac OS X is via Homebrew:

$ brew install amber-crystal/amber/amber

Refer to this link if you don't have homebrew installed.

Commands

$ amber --help
amber [OPTIONS] SUBCOMMAND

Amber

The `amber new` command creates a new Amber application with a default
directory structure and configuration at the path you specify.

You can specify extra command-line arguments to be used every time
`amber new` runs in the .amber.yml configuration file in your project
root directory

Note that the arguments specified in the .amber.yml file does not affect the
defaults values shown above in this help message.

Usage:
amber new [app_name] -d [pg | mysql | sqlite] -t [slang | ecr] --deps

Commands:
  amber c console                 # Starts a amber console   
  amber g generate [SUBCOMMAND]   # Generate Amber classes
  amber n new                     # Generate a new amber project
  amber m migrate [SUBCOMMAND]    # Performs database migrations tasks
  amber w watch                   # Starts amber server and rebuilds on file changes
  amber routes                    # Prints the routes (In Development)
  amber r run [OPTION]            # Compiles and runs your project. Options: [-p --port | -e -environment]

Options:
  -t, --template [name]           # Preconfigure for selected template engine. Options: slang | ecr
  -d, --database [name]           # Preconfigure for selected database. Options: pg | mysql | sqlite
  -h, --help                      # Describe available commands and usages
  -v, --version                   # Prints Amber version
  --deps                          # Installs project dependencies

Example:
  amber new ~/Code/Projects/weblog
  This generates a skeletal Amber installation in ~/Code/Projects/weblog.

Usage

amber new [your_app] -d [pg | mysql | sqlite] -t [slang | ecr] --deps
cd [your_app]

options: -d defaults to pg. -t defaults to slang. --deps will run crystal deps for you.

This will generate a traditional web application:

  • /config - Application and HTTP::Handler config's goes here. The database.yml and routes.cr are here.
  • /lib - shards are installed here.
  • /public - Default location for html/css/js files. The static handler points to this directory.
  • /spec - all the crystal specs go here.
  • /src - all the source code goes here.

Scaffolding

Generate scaffolding for a resource:

amber generate scaffold Post name:string body:text draft:bool

This will generate scaffolding for a Post:

  • src/controllers/post_controller.cr
  • src/models/post.cr
  • src/views/post/*
  • db/migrations/[datetimestamp]_create_post.sql
  • spec/controllers/post_controller_spec.cr
  • spec/models/post_spec.cr
  • appends route to config/routes.cr
  • appends navigation to src/layouts/_nav.slang

Running App Locally

To test the generated App locally:

  1. Make sure your app has the right credentials via the following methods:
  • Add it in config/database.yml or
  • Run export DATABASE_URL=postgres://[username]:[password]@localhost:5432/[your_app]_development which overrides the config/database.yml.
  1. Migrate the database: amber db create migrate. You should see output like Migrating db, current version: 0, target: [datetimestamp]OK [datetimestamp]_create_shop.sql
  2. Run the specs: crystal spec
  3. Start your app: amber watch
  4. Then visit http://0.0.0.0:3000/

Note: The amber watch command uses Sentry to watch for any changes in your source files, recompiling automatically.

If you don't want to use Sentry, you can compile and run manually:

  1. Build the app crystal build --release src/[your_app].cr
  2. Run with ./[your_app]
  3. Visit http://0.0.0.0:3000/

Amber Philosophy H.R.T.

It's all about the community. Software development is a team sport!

It's not enough to be brilliant when you're alone in your programming lair. You are not going to change the world or delight millions of users by hiding and preparing your secret invention. We need to work with other members, we need to share our visions, divide the labor, learn from others, we need to be a team.

HUMILITY We are not the center of the universe. You're neither omniscient nor infallible. You are open to self-improvement.

RESPECT You genuinely care about others you work with. You treat them as human beings and appreciate their abilities and accomplishments.

TRUST You believe others are competent and will do the right thing, and you are OK with letting them drive when appropriate.

Code of Conduct

We have adopted the Contributor Covenant to be our CODE OF CONDUCT guidelines for Amber.

Have a Amber based project?

Use Amber badge Amber Framework

[![Amber Framework](https://img.shields.io/badge/using-amber%20framework-orange.svg)](Your project url)

Contributing

Contributing to Amber can be a rewarding way to learn, teach, and build experience in just about any skill you can imagine. You don’t have to become a lifelong contributor to enjoy participating in Amber.

Amber is a community effort and we want You to be part of ours Join Amber Community!

  1. Fork it ( https://github.com/amber-crystal/amber_cmd/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

Amber Core Team

License

This project is licensed under the MIT License - see the LICENSE file for details

Acknowledgments

  • Inspired by Kemal, Rails, Phoenix, Hanami