Productivity. Performance. Happiness.

Maze makes building web applications fast, simple, and enjoyable - with fewer bugs and blazing fast performance.

Welcome to Maze

Maze is a web application framework written in Crystal inspired by Kemal, Rails, Phoenix and other popular application frameworks and based on Amber. The purpose of Maze is to extend Amber with specific features and design goals that are outside of, and sometimes incompatible with, the core goals of the Amber project.

Work In Progress

This is very much a work in progress, especially documentation. Most Amber documentation will still apply. Links may not work yet until all elements are imported from Amber. Maze is primarily meant to be an agile testing ground for new features that may or not be integrated into the Amber project at a later date. Amber has an existing user community so care needs to be taken to ensure things do not break for existing users.

The most important difference between Amber and Maze is a modular code layout as default rather than the code layout developers coming from Rails will be familiar with. With Amber, anyone coming from a Rails background will feel right at home as the default Amber application layout has many similarities with Rails, e.g. Model, Views and Controllers are contained in app/models, app/views and app/controllers directories respectively. If what you are looking for is a Rails like experience then you may be better off heading over to Amber.

Maze takes a modular approach whereby the code for a feature is organised in modules. Modules are a core principle of OOP and anyone who has used MEAN.js will be familiar with this code layout scheme. One of the principle advantages is that all artifacts for a particular feature are located in the same folder, making navigation between the different artifacts easier, especially in large code bases. For example given an application feature to perform CRUD operations on Post objects (e.g. title, bodytext etc.) The code layout in Maze for the Post module would be as such (using the slang template engine);

src/modules
src/modules/post
src/modules/post/_form.slang
src/modules/post/edit.slang
src/modules/post/post_controller.cr
src/modules/post/show.slang
src/modules/post/post.cr    # the Post model
src/modules/post/index.slang
src/modules/post/new.slang

This does not preclude models, views and controllers in the src/models, src/views and src/controllers directories. That layout scheme is still available and a Maze app can contain code in both layouts simultaneously. The difference between the two layout schemes is in the render() method. For the standard Rails/Amber paradigm render a template (and partial) with the render method. For the modular paradigm render a template (and partial) with the render_module method.

Amber has a recipes feature whereby an application can be created with a modular layout. However in future it may prove difficult to maintain recipes that need to support both the default (Rails like) layout and the modular layout.

Principle enhancements

At the moment the principle enhancements envisioned are;

• bare bones base system
• hierarchical recipe/plugin generators
• extend base with plugins for ORM, template, database drivers during app generation
• recipe/plugin generators only, no internal generators
• plugin code modules (i.e. something like Rails engines)
• generator hooks

Bare bones system

A bare Maze application will have no ORM, template engine or database drivers installed. When generating a new application command line arguments will add these features to the app being generated and or the user can add them via plugins later.

Hierarchical Recipes

Recipes are code generators that generate applications and application artifacts with a particular format and functionality. Recipes will depend on other recipes. A recipe will first process it's dependencies before processing itself.

Extensions

A recipe could define the base recipe, an ORM, a database driver and a template engine as dependencies to create an application with particular flavours of these artifacts.

Recipe/Plugin generators

All application artifacts to be generated by recipes and plugins. A recipe is a collection of templates that defines the layout of an application, model, controller and scaffolding whereas a plugin provides an individual code feature.

Plugins

One of the principle goals of Maze will be the ability to drop in self contained software modules from community contributed plugins and modular code layout should make this considerably easier.

Generator hooks

Recipes and plugin will be able to define Before and After hooks. Recipes will be able to also define Before and After hooks for each artifact type in the recipe.

Philosophy

Another goal of Maze will be a distinct separation between core Maze artifacts and local application artifacts so that the Maze system can be updated without affecting the application code base.

Community

Questions? Join our IRC channel #maze and Gitter room or ask on Stack Overflow under the maze-framework tag.

Guidelines? We have adopted the Contributor Covenant to be our CODE OF CONDUCT for Maze.

Our Philosophy? Read Maze Philosophy H.R.T.

Documentation

Read Maze documentation on https://mazeframework.gitbook.io/maze/

Amber Benchmarks

Techempower Framework Benchmarks - Round 15 (2018-02-14)

Fortunes test comparing Amber, Kemal, Rails, Phoenix, and Hanami:

Installation & Usage

MacOS or Linux

git clone https://github.com/mazeframework/maze.git
cd maze
git checkout stable
make
sudo make install

Common

To compile a local bin/maze per project use shards build maze

To use it as dependency, add this to your application's shard.yml:

dependencies:
  maze:
    github: mazeframework/maze

Read more about Maze CLI installation guide

Read Maze guide from zero to deploy

Read Maze CLI commands usage

Have a Maze-based Project?

Use Maze badge

[![Maze Framework](https://img.shields.io/badge/using-maze-framework-orange.svg)](https://mazeframework.gitbook.io)

Contributing

Contributing to Amber and Maze 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 and Maze. If you develop new features, bug fixes or improvements to Maze please consider submitting your changes to Amber as well, and vice-versa.

Tracking issues? Check our project board.

Code Triage? Join us on codetriage.

Maze is a community effort and we want You to be part of it. Join Maze Community!

1. Fork it https://github.com/mazeframework/maze/fork
2. Clone your fork to your local workstation
3. Create your feature branch git checkout -b my-new-feature
4. Write and execute specs crystal spec
5. Verify with Docker docker-compose build spec; docker-compose run spec
6. Commit your changes git commit -am 'Add some feature'
7. Push to the branch git push origin my-new-feature
8. Create a new Pull Request

Keep your fork up to date

For existing forks, before creating a new branch ensure your master branch is up to date.

# create upstream remote if not already created
git remote add upstream git@github.com:mazeframework/maze.git

# fetch the upstream and merge the master branches
git checkout master
git fetch upstream
git merge upstream/master
git checkout -b my-new-feature

If developing a new feature takes a long time you will need to rebase your branch from time to time. Fetch and merge upstream/master as per the instructions above and rebase with

git checkout my-new-feature
git rebase master

Contributors

• Damian Hamill

See more Maze contributors

Amber Contributors

• Dru Jensen
• Elias Perez
• Isaac Sloan
• Faustino Aguilar
• Nick Franken
• Mark Siemers
• Robert Carpenter

License

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

Acknowledgments

• Based on Amber
• Inspired by Kemal, Rails, Phoenix, and Hanami,