omahajs / generator-omaha

A Yeoman generator for the modern front-end artisan designed to help you craft sustainable code for the web.

Quick Start

✔ Install Yeoman CLI tool, Grunt CLI tool, and generator-omaha node module globally

npm install --global yo grunt-cli generator-omaha

✔ Create an empty directory and cd into it

mkdir my-project && cd my-project

✔ Run omaha generator

yo omaha

✔ Make some choices

Patterns are Paramount

generator-omahastrives to enable developers of various skill and experience to more easily implement patterns and architectures with minimal time and effort. Specifically, generator-omaha enables the following patterns and capabilities:

• Composite architecture using Marionette.js, "The Backbone Framework"
• Event driven interactions using Backbone.Radio
• View templating with Handlebars (or Lodash) and template pre-compilation
• Predictable state management with Redux
• Workflow with support for linting, optimization, testing, bundling, documentation and transpilation.
• End-to-end (E2E) browser testing with Nightwatch.js

The default sub-generator may be for a web app, but generator-omaha also has sub-generators for crafting:

• servers built on express with security baked in (using lusca and helmet)
• plugins to support a modular architecture
• projects with pre-configured modern workflows
• native desktop applications built on Electron --> quickly turn your web app into a desktop app!

Typical Workflows

After scaffolding a new project with yo omaha ...

• Serve live-reload enabled app with companion RESTful API using npm start, then...
  • ✨ lint your code in real-time with a second terminal running npm run lint:watch
  • 💯 run tests and calculate code coverage in real-time with npm run test:watch
  • 💄 see your style updates and code changes in the browser with a second terminal running grunt styling
• Run tests with npm test
• One-time lint with npm run lint
• Run tests and lint code as a watch task in one terminal with: npm run dev (linux only)
• Demo your bundled project in a browser with npm run demo
• View reports, documentation and styleguide:
  • code coverage: grunt cover open:coverage
  • JSDocs documentation: grunt docs open:docs
  • Living styleguide: grunt docs open:styleguide
• Review the code to see all the available tasks

View the lint rules that make your code more secure

Command Line Options

Beyond yo omaha --help

• Scaffold a web app after making some choices via prompts (options are not honored without the use of --defaults)

yo omaha

• Scaffold a web app "auto-magically" with defaults and no user input

yo omaha --defaults

• Use "silent" webapp defaults, skip support for everything, and select custom source directory

yo omaha --defaults --slim --src src

• Use "silent" web app defaults with Webpack

yo omaha --defaults --use-webpack

• Use "silent" web app defaults with Browserify and Jest

yo omaha --defaults --use-browserify --use-jest

• Use "silent" web app defaults with custom modifications

yo omaha --defaults --template-technology lodash --skip-coveralls

Available options

Default in bold

• --defaults: scaffold app with no user input using defaults
• --slim: use with --defaults to perform "slim" install (all options skipped)
• --src: use with --defaults to select custom source directory for app and assets files
• --amd: use AMD module format (with r.js as script bundler)
• --use-browserify: use Browserify as script bundler (auto selects CommonJS module format)
• --use-jest: use Facebook's Jest instead of mocha (auto selects CommonJS module format)
• --use-webpack: use Webpack as script bundler (auto selects CommonJS module format and Jest test framework)
• --use-rust: Add folder structure, sample file, and build scripts for WebAssembly development using Rust (rustc and wasm-gc required)
• --skip-imagemin: use with --defaults
• --css-preprocessor: less | sass | none
• --template-technology: handlebars | lodash

But wait, there's more! Read about all the available generators!

Alternatives

• See wiki page: Tools for Creating Web Apps

Credits

• Yeoman (d'uh)
• railroad-diagrams
• electron-forge
• All the awesome open source projects that make this project possible

A Note on Semantic Versioning

This project strives to follow the principles of semantic versioning (semver). However, it seems unreasonable to release major versions for changes to the generated output of generator-omaha that are not backwards compatible with the generated output of previous versions. In general, this project will release major versions when the generator API is not backwards compatible or when the generated outputs undergo substantial changes. In the case of the latter, a major version increment would serve more as a signifier of significant change (not necessarily changes that are not backwards compatible). I am perhaps making this more complicated than necessary; however, I want to avoid superficial "churn" while still maintaining a standardized process for development and enhancement.

License