node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

zab

Zab Logo Build Status



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 run zab 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 use about.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 in build are relative to this path.
    • transforms An array of browserify transforms you want to use in your build. Uses babelify for ES6 support, and envify allowing you to use environment variables. ex. ["vueify", "coffeeify"]
    • processor
      • css [default: stylus] Defines the preprocessor for CSS. Can currently be set to stylus or scss.
    • 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, and bower_components. These cannot be overwritten.
    • cdnPrefix [default: none] Will automatically prefix this url to all assets in your HTML and CSS on zab 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.