README
What is Zab?
Zab is a service for building, hosting, and managing static websites. This is the Zab toolkit built in NodeJS, which includes a powerful watcher/builder system, a static server for running your projects locally, and integrates seamlessly with Zab hosting so you can have an end-to-end solution for your website or app.
Installation
You need Node on your local machine to run Zab. Install it using NVM for OSX/Linux or NVMW for Windows. Then:
npm install -g zab
or to use as middleware
npm install --save zab
Quick Start
zab new myApp
# answer questions
cd myApp && zab watch -o
That's it! Your site is now running at http://localhost:8080
, and will rebuild and auto-reload when you change a file. You can customize the behavior of the server by modifying the config file (read on).
Config
The zab.json
config file is automatically created in your project folder when zab new
or zab init
is run. It can be used to customize your project and server.
name
The name of your app, in reference to Zab hosting. To rename your app, you can runzab app rename <new-name>
. This is also your unique Zab subdomain (ex.[name].zab.io
).root
[default:dist
] Sets the root folder of your compiled site (where your index.html lives).host
[default:localhost
] The host used by the local server. This will be overridden by the HOST environment variable if set.port
[default:8080
] The port used by the local server. This will be overridden by the PORT environment variable if set.errorPage
Sets a custom error page used whenever a 404 error is thrown in your application. Will default to Zab's 404 page.cleanUrls
[default:true
] Allows for routes without a file extension to default as an html page (zab.io/about
will useabout.html
under the hood). The server will not redirect the.html
extension by default, but this can be defined as a redirect.forceSSL
[default:false
] Forces your site to be accessed over https. Only enable this if you have a valid SSL certificate configured on your site at the DNS level!proxies
An array containing custom proxy objects. Prioritized from top to bottom. Supports glob-style patterns and regex-style replacements. See Proxies for examples.src
The source url you want to proxy.dest
The destination url for the proxy.headers
An array of headers to send to your proxy origin (see Headers for structure).
redirects
An array containing custom redirect objects. Prioritized from top to bottom. Supports glob-style patterns and regex-style replacements. See Redirects for examples.src
The source url you want to redirect.dest
The destination you want to resolve to.code
[default:301
] The http status code to return (301 or 302).
routes
An array containing custom route objects. Prioritized from top to bottom. Supports glob-style patterns and regex-style replacements. See Routes for examples.src
The source url you want to redirect.dest
The destination you want to resolve to.
headers
An array containing custom header objects that are set on your site. See Headers for examples.name
The name of your header.value
The value of your header.
data
[default:data.json
] The path to your CMS file, which is used for templates.liveReload
[default:true
] Enables live reload while running the watcher.build
path
[default:src
] The root path to your source files directory. All following paths inbuild
are relative to this path.transforms
An array of browserify transforms you want to use in your build. Usesbabelify
for ES6 support, andenvify
allowing you to use environment variables. ex.["vueify", "coffeeify"]
processor
css
[default:stylus
] Defines the preprocessor for CSS. Can currently be set tostylus
orscss
.
compile
js
[default:scripts/app.js
] Path to your javascript insertion file.css
[default:styles/app.styl
] Path to your css insertion file.html
[default:views
] Path to your views directory.assets
[default:assets
] Path to your assets directory.
watch
js
[default:['scripts/**']
] An array of glob-patterns to watch for changes to javascript files.css
[default:['styles/**']
] An array of glob-patterns to watch for changes to style files.html
[default:['views/**']
] An array of glob-patterns to watch for changes to view files.assets
[default:['assets/**']
] An array of glob-patterns to watch for changes to asset files.
ignore
An array of glob-patterns to ignore while watching files. Default values are dotfiles,node_modules
, andbower_components
. These cannot be overwritten.cdnPrefix
[default: none] Will automatically prefix this url to all assets in your HTML and CSS onzab build
. Only use this if you are NOT using Zab hosting. Otherwise your deployments will not work as expected.cdnex
[default: none] A configuration object for Cdnex
Proxies
Proxies are a powerful feature in Zab. They allow you to mask outside urls to routes in your site. This is useful to solve CORS issues, to mask the url of your APIs, and many other things. You can also send custom headers to the destination, following the same structure as headers. Supports glob-patterns in the source, and regex-style replacements in the destination. Prioritized from top to bottom. Proxies take precedence over redirects and routes. Automatically sets the Host
header to the host of the destination (can be overwritten).
"proxies": [
{
"src": "/api/**",
"dest": "https://api.zab.io/$1",
"headers": [
{"name": "x-forwarded-host", "value": "mysite.com"}
]
}
]
With the above example, going to mysite.com/api/user/12345
will proxy the request to https://api.zab.io/user/12345
. This is different than a redirect, because users will still see the original url with mysite.com
in their address bar.
Redirects
Allows for custom redirects to be defined. Supports glob-patterns in the source, and regex-style replacements in the destinations. You can also redirect to outside sites by using an absolute url. Prioritized from top to bottom. Redirects take precedence over routes.
"redirects": [
{"src": "/old/path", "dest": "/new/path"},
{"src": "/old/path/**", "dest": "/new/path/$1", "code": 302},
{"src": "/other/path/*/*", "dest": "/path/$1/$2"},
{"src": "/google/*", "dest": "https://www.google.com/#q=$1"}
]
Each glob-style star will match up with a regex replacement variable (a number following the $
sign). These line up with the order the stars are in. For example, if you have the redirect { "src": "/blog/*/*", "dest": "/$2" }
, going to mysite.com/blog/posts/why-zab-is-awesome
will return a 301 redirect to mysite.com/why-zab-is-awesome
. In the destination, $1 == posts
and $2 == why-zab-is-awesome
.
Routes
Allows for custom routes to be defined. This works great for single-page apps with pushState enabled, such as a React or Angular app. Supports glob-patterns in the source, and regex-style replacements in the destination. Prioritized from top to bottom. Any URL with a file extension will bypass the router.
"routes": [
{"src": "/about", "dest": "aboutUs.html"},
{"src": "/contact", "dest": "contact-page.html"},
{"src": "/blog/**", "dest": "blog_$1.html"},
{"src": "/**", "dest": "index.html"}
]
With the above example, going to any url other than /about
, /contact
or /blog/**
will use index.html
in the background. Going to /blog/why-zab-is-awesome
will use blog_why-zab-is-awesome.html
.
Headers
A simple object with the key as the header name, and the value as the header value that allows for custom headers to be returned in your site's response.
"headers": [
{"name": "Access-Control-Allow-Origin", "value": "*"},
{"name": "X-Site-Awesomeness", "value": "Maxed"}
]
Javascript Preprocessing
- Preprocessed with Babel & JSX. ES6 ftw!
- Compiled with Browserify
CSS Preprocessing
- Preprocessed with Stylus or SCSS
- If you want to use vanilla CSS, put it in your assets folder
- More preprocessors to come...
HTML Templating
- Built in support for Jade
- Any files prefixed with an
_
(eg. _layout.jade), will not be compiled - Data from
data.json
will be interpolated into your templates (if you're using Jade) - More templating languages to come...
Middleware
You can use Zab as middleware, but implementation of this is still in progress. Better support and documentation is coming soon.
Hosting
Zab offers high-end static website hosting. If you agreed to using our hosting when you created your app, you can run zab deploy
at any time to deploy your site. If you want to enable hosting in an existing Zab app, simply run zab init
in the project folder. If you don't have an account yet, you can run zab signup
to join us!
Your App
You can run commands for your current app (such as seeing your custom domains or deleting your app) by running zab app [cmd]
. To see a list of all the available commands, run zab help app
.
ex. zab app list
will show you all of your apps.
Custom Domains
You can map custom domains to your site by running zab domain add www.customdomain.com
, then creating a CNAME in your DNS, and pointing to your Zab subdomain (www.customdomain.com CNAME myapp.zab.io
). If you want to use your apex domain (without the www), you can use any popular DNS provider that supports this, such as CloudFlare. Run zab help domain
for a list of all commands.
You can run zab app info
to see a list of your custom domains, and other info about your current app.
Using your API Key
You can get your API key by running zab api-key get
and entering your password. You can use this key to authenticate any command by including it with --key or -k
. (ex. zab deploy --key [YOUR_KEY]
).
KEEP YOUR KEY SECRET! If someone gets it, they can take control of your account. Make sure you don't commit your key to any git repos, or make it visible to the public in any way. If your key is compromised, you can get a new one by running zab api-key roll
.
Help & Contributing
If you need additional help with the CLI, you can run zab --help
for all the available commands, and zab help [command]
for help with a specific command.
To use the cutting-edge version of Zab (from the master branch), you can install with npm install -g zab/zab-cli
, or clone this repo and run cd zab-cli && npm install && npm link
to link it to your global path.
Zab is still in beta, so if you come across a bug or want to submit an additional feature, please create a new issue. If you wish to contribute or be a part of it, visit us at zab.io for more info, and be sure to sign up for our mailing list. We're also happy to review any pull requests!
Testing
npm test
Not fully tested yet, but this will come soon.
Community
If you plan on using Zab or just want to chat about static websites or front-end development, join us on Slack.
Copyright & License
Copyright © 2016 Zab · Licensed under the MIT license.