From e331afb2fb35023700c9b0c7dc5a831107c64bbb Mon Sep 17 00:00:00 2001 From: Justin Searls Date: Tue, 11 Mar 2014 20:15:06 -0400 Subject: [PATCH 1/8] Start work on a Lineman chapter --- chapters/scaffolding/lineman/assets/.gitkeep | 0 .../scaffolding/lineman/getting-started.md | 63 +++++++++++++++++++ chapters/scaffolding/lineman/introduction.md | 27 ++++++++ chapters/scaffolding/lineman/references.md | 4 ++ .../scaffolding/lineman/troubleshooting.md | 1 + 5 files changed, 95 insertions(+) create mode 100644 chapters/scaffolding/lineman/assets/.gitkeep create mode 100644 chapters/scaffolding/lineman/getting-started.md create mode 100644 chapters/scaffolding/lineman/introduction.md create mode 100644 chapters/scaffolding/lineman/references.md create mode 100644 chapters/scaffolding/lineman/troubleshooting.md diff --git a/chapters/scaffolding/lineman/assets/.gitkeep b/chapters/scaffolding/lineman/assets/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/chapters/scaffolding/lineman/getting-started.md b/chapters/scaffolding/lineman/getting-started.md new file mode 100644 index 0000000..bc75cb6 --- /dev/null +++ b/chapters/scaffolding/lineman/getting-started.md @@ -0,0 +1,63 @@ +# Getting started + +## Installation + +Lineman is a Node.js-based tool, and it requires `npm` to install it. + +Lineman is installed globally: + +```bash +npm install -g lineman +``` + +You can test it by running: + +```bash +lineman --version +``` + +## Creating a project + +To create a new lineman project, just run: + +```bash +lineman new some-project-name +``` + +This will create a project in `some-project-name/` with a small scaffold of directories and files. It'll include several safe-to-delete example files. Once you're comfortable, you may want to generate the project again with the "--skip-examples" flag to start completely fresh. + +## Developing + +Once you've changed into your project directory, you can see your app in action by running: + +``` bash +lineman run +``` + +This will do an initial build of the application into a transient folder named "generated/" and start a local server out of that directory. You can access it at [localhost:8000](http://localhost:8000). + +The `run` command also watches for file changes, re-running any appropriate tasks. It also exposes powerful API proxying and stubbing tools that let you develop your web application in concert with other backend services (whether or not they actually exist yet). + +## Building + +When you're ready to deploy, run: + +``` bash +lineman build +``` + +And this will build a ready-to-deploy set of artifacts in a directory named "dist/". By default, this means minifying your scripts & stylsheets. + +## Configuration + +TODO: configuring asset fingerprinting + +TODO: Setting up an API proxy + +TODO: API Stubbing + +TODO: deploying to heroku + +TODO: Ruby on Rails integration + +TODO: using Lineman plugins diff --git a/chapters/scaffolding/lineman/introduction.md b/chapters/scaffolding/lineman/introduction.md new file mode 100644 index 0000000..028c851 --- /dev/null +++ b/chapters/scaffolding/lineman/introduction.md @@ -0,0 +1,27 @@ +# Lineman + +## What is Lineman? + +[Lineman.js](http://linemanjs.com) is a command-line tool that can build a ready-to-deploy modern web application out-of-the-box. + +Lineman's ready-to-deploy behavior is accomplished by way of a number of its conventions about how web applications should be structured (e.g. client-side JavaScript should be placed under "app/js", whereas third-party stylesheets should be placed under "vendor/css"). This aspect of Lineman was heavily inspired by [Ruby on Rails](http://rubyonrails.org), aiming to occupy a niche of convention-oriented workflow tools for the Node.js community. + +The real value of Lineman is that it can help you get started working on a project very easily, all without enforcing any opinions about the front-end application frameworks you use. + +Additionally, Lineman projects tend to be easy-to-upgrade because generated files are kept to a minimum. Literally any configuration property can be overridden dynamically, so each Lineman project only needs to declare how it's different from the norm, without any boilerplate describing how its defaults. + +You can grow your project's toolset by installing Lineman plug-ins, which take the form of community-managed Lineman configurations. Like Lineman itself, the tasks and configuration included by plugins are dynamically applied and as such, won't clutter your application's repo. Also like Lineman, anything a plugin can do can be just as easily overridden when your needs differ from the norm. + +## How does Lineman work, technically? + +Lineman depends on Grunt and, no less importantly, the terrific Grunt community for the implementation of all the individual build tasks a web project might make use of. + +You can think of Lineman as a sort of workflow-aware Grunt configuration aggregator. Lineman itself, its plugins, and users' projects each contribute to one entire grunt task configuration. + +Managing Grunt's configuration is useful for providing defaults, enabling extensions, and allowing for user overrides. On its own, this has some value, as it prevent the same massive Gruntfile from being copied and pasted from project to project. Where Lineman really shines, however, is by organizing all of a project's grunt tasks into ordered task lists that describe the workflows needed by every application: + +* Activities that need to happen regardless of how we build the app +* Tasks that need to run, but only when developing +* Deployment-minded tasks that only need to run when it's time to distribute the app. + +From a user's perspective, these tasks are exposed through Lineman's CLI commands (`lineman run`, `lineman build`, `lineman spec`, and so on). diff --git a/chapters/scaffolding/lineman/references.md b/chapters/scaffolding/lineman/references.md new file mode 100644 index 0000000..4646275 --- /dev/null +++ b/chapters/scaffolding/lineman/references.md @@ -0,0 +1,4 @@ +# References + +* [http://linemanjs.com](http://linemanjs.com) +* [https://github.com/linemanjs/lineman](https://github.com/linemanjs/lineman) diff --git a/chapters/scaffolding/lineman/troubleshooting.md b/chapters/scaffolding/lineman/troubleshooting.md new file mode 100644 index 0000000..64a80c8 --- /dev/null +++ b/chapters/scaffolding/lineman/troubleshooting.md @@ -0,0 +1 @@ +# Troubleshooting \ No newline at end of file From 1f23181eb92638002e7efe7b0c4920c20296c85f Mon Sep 17 00:00:00 2001 From: iampeterbanjo Date: Mon, 21 Sep 2015 10:39:13 +0100 Subject: [PATCH 2/8] Setting up an API proxy --- chapters/scaffolding/lineman/getting-started.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/chapters/scaffolding/lineman/getting-started.md b/chapters/scaffolding/lineman/getting-started.md index bc75cb6..01822e6 100644 --- a/chapters/scaffolding/lineman/getting-started.md +++ b/chapters/scaffolding/lineman/getting-started.md @@ -52,7 +52,19 @@ And this will build a ready-to-deploy set of artifacts in a directory named "dis TODO: configuring asset fingerprinting -TODO: Setting up an API proxy +## Setting up an API proxy + +API proxying allows your front-end Lineman app to send requests to your back-end application on another port. For example if you have a Ruby on Rails application on port 3000 and your Lineman app is on port 8000 you can configure Lineman requests to be proxied to port 3000 like this: + +``` js +// config/application.js +server: { + apiProxy: { + enabled: true, + port: 3000 + } +} +``` TODO: API Stubbing From 89dc9c23ed88921a6543247fc7b9bde334590490 Mon Sep 17 00:00:00 2001 From: iampeterbanjo Date: Mon, 21 Sep 2015 10:45:31 +0100 Subject: [PATCH 3/8] API stubbing --- chapters/scaffolding/lineman/getting-started.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/chapters/scaffolding/lineman/getting-started.md b/chapters/scaffolding/lineman/getting-started.md index 01822e6..f6a1676 100644 --- a/chapters/scaffolding/lineman/getting-started.md +++ b/chapters/scaffolding/lineman/getting-started.md @@ -58,6 +58,7 @@ API proxying allows your front-end Lineman app to send requests to your back-end ``` js // config/application.js + server: { apiProxy: { enabled: true, @@ -66,7 +67,21 @@ server: { } ``` -TODO: API Stubbing +## API Stubbing + +API stubbing is intended to be a rapid prototyping tool that allows you to quickly validate the specifications for your front-end app. As such, it is only available on the development server and is also not available in Lineman's built in unit test suite run with `lineman spec`. API stubs are routes which respond with a pre-configured response, for example, + +``` js +// config/server.js + +module.exports = { + drawRoutes: function(app) { + app.get('/api/greeting/:message', function(req, res){ + res.json({ message: "OK, "+req.params.message }); + }); + } +}; +``` TODO: deploying to heroku From 430485c93b2eaf555a20ea0da8a4d1422a171595 Mon Sep 17 00:00:00 2001 From: iampeterbanjo Date: Mon, 21 Sep 2015 10:50:11 +0100 Subject: [PATCH 4/8] Deploying to heroku --- chapters/scaffolding/lineman/getting-started.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/chapters/scaffolding/lineman/getting-started.md b/chapters/scaffolding/lineman/getting-started.md index f6a1676..940b6ea 100644 --- a/chapters/scaffolding/lineman/getting-started.md +++ b/chapters/scaffolding/lineman/getting-started.md @@ -69,7 +69,7 @@ server: { ## API Stubbing -API stubbing is intended to be a rapid prototyping tool that allows you to quickly validate the specifications for your front-end app. As such, it is only available on the development server and is also not available in Lineman's built in unit test suite run with `lineman spec`. API stubs are routes which respond with a pre-configured response, for example, +API stubbing is intended to be a rapid prototyping tool that allows you to quickly validate the specifications for your front-end app. As such, it is only available on the development server and is also not available in Lineman's built in unit test suite run with `lineman spec`. API stubs are routes which respond with a pre-configured response, for example: ``` js // config/server.js @@ -83,7 +83,13 @@ module.exports = { }; ``` -TODO: deploying to heroku +## Deploying to heroku +Once you have heroku [toolbelt installed](https://toolbelt.heroku.com/), simply run this from your project: +``` bash +$ heroku create +$ heroku config:set BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-nodejs +$ heroku config:set NPM_CONFIG_PRODUCTION=false +``` TODO: Ruby on Rails integration From 5f191e3c72352b1b65489aab169b2b6cf1f87a6d Mon Sep 17 00:00:00 2001 From: iampeterbanjo Date: Mon, 21 Sep 2015 11:14:25 +0100 Subject: [PATCH 5/8] Lineman plugins --- .../scaffolding/lineman/getting-started.md | 40 ++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/chapters/scaffolding/lineman/getting-started.md b/chapters/scaffolding/lineman/getting-started.md index 940b6ea..44ef0e2 100644 --- a/chapters/scaffolding/lineman/getting-started.md +++ b/chapters/scaffolding/lineman/getting-started.md @@ -93,4 +93,42 @@ $ heroku config:set NPM_CONFIG_PRODUCTION=false TODO: Ruby on Rails integration -TODO: using Lineman plugins +## Lineman plugins +Lineman aims to be focused on sensible default task configuration and some level of build awareness. A plugin architecture allows you to break up large configurations down into more focused ones which are likely to be comman across multiple projects. [Published plugins](https://www.npmjs.com/search?q=lineman) can be installed using npm: +``` bash +$ npm install --save-dev lineman-jade +``` + +## Creating plugins +A Lineman plugin has the following requirments: + +1. Every plugin's name must start with "lineman-" in order to be discovered and auto-loaded by Lineman. +2. The plugin's `package.json` file should declare "lineman" as a peer dependency: +``` js +// package.json + +"peerDependencies": { + "lineman": ">= 0.24.0" +} +``` +3. Any grunt task modules or other runtime dependencies you need should be included in the "dependencies" object so that they will be installed and available to the end user. + +A plugin file closely resembles the format of each project's `config/application` and `config/files` files. JavaScript and Coffeescript files under `config/plugins` will be automatically pickedup and run by Lineman and merged into your project configuration. An example of a plugin file is: + +``` js +// config/plugins/my-task-here.{js,coffee} + +module.exports = function(lineman) { + return { + files: { + //Any file patterns you have can go here + }, + config: { + //Any project & task configurations go here + } + }; +}; +``` +The provided `lineman` object exposes the current configuration (as it exists prior to loading your plugin file) under `lineman.config`. Concat any array-type configuration values to avoid overwriting them entirely. For example, setting `loadNpmTasks: ["my-task-module"]` would overwrite all the tasks loaded by previous plugins. Use `loadNpmTasks: lineman.config.application.loadNpmTasks.concat("my-task-module")` instead. + +Test your plugin with a local project using [npm link](https://docs.npmjs.com/cli/link) before publishing. From d7cdd2507891d163985a35a4dfc90193dfd43e32 Mon Sep 17 00:00:00 2001 From: iampeterbanjo Date: Mon, 21 Sep 2015 11:15:48 +0100 Subject: [PATCH 6/8] Fix typo in Lineman plugins --- chapters/scaffolding/lineman/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/scaffolding/lineman/getting-started.md b/chapters/scaffolding/lineman/getting-started.md index 44ef0e2..d5e9de7 100644 --- a/chapters/scaffolding/lineman/getting-started.md +++ b/chapters/scaffolding/lineman/getting-started.md @@ -113,7 +113,7 @@ A Lineman plugin has the following requirments: ``` 3. Any grunt task modules or other runtime dependencies you need should be included in the "dependencies" object so that they will be installed and available to the end user. -A plugin file closely resembles the format of each project's `config/application` and `config/files` files. JavaScript and Coffeescript files under `config/plugins` will be automatically pickedup and run by Lineman and merged into your project configuration. An example of a plugin file is: +A plugin file closely resembles the format of each project's `config/application` and `config/files` files. JavaScript and Coffeescript files under `config/plugins` will be automatically picked-up and run by Lineman and merged into your project configuration. An example of a plugin file is: ``` js // config/plugins/my-task-here.{js,coffee} From 1f17b341009219ae2c2b9a041ba704aa985ca556 Mon Sep 17 00:00:00 2001 From: iampeterbanjo Date: Mon, 21 Sep 2015 11:35:48 +0100 Subject: [PATCH 7/8] Ruby on Rails integration --- chapters/scaffolding/lineman/getting-started.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/chapters/scaffolding/lineman/getting-started.md b/chapters/scaffolding/lineman/getting-started.md index d5e9de7..4979971 100644 --- a/chapters/scaffolding/lineman/getting-started.md +++ b/chapters/scaffolding/lineman/getting-started.md @@ -91,7 +91,22 @@ $ heroku config:set BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-nod $ heroku config:set NPM_CONFIG_PRODUCTION=false ``` -TODO: Ruby on Rails integration +## Ruby on Rails integration +Lineman can be integrated with your Ruby on Rails project via the `lineman-rails` plugin and `rails-lineman` gem. + +In your Ruby on Rails app: + +1. Add this to your Gemfile: `gem 'rails-lineman'` +2. Tell the gem where to look for Lineman: `config.rails_lineman.lineman_project_location = "my/app"`. You can also set an environment variable called **LINEMAN_PROJECT_LOCATION** +3. Include Lineman's CSS & JavaScript: `<%= stylesheet_link_tag "lineman/app" %> <%= javascript_include_tag "lineman/app" %>` +4. Boot your Rails server: `$ bundle exec rails s` +5. When you deploy, Lineman assets will be built and included: `$ rake assets:precompile` + +In your Lineman app: + +1. Install Lineman's Rails plugin. This will setup some additional static routes and enable the API proxy: `$ npm install --save-dev lineman-rails` +2. Start your Lineman server: `$ lineman run` +3. During development use Lineman's server: `$ open http://localhost:8000` ## Lineman plugins Lineman aims to be focused on sensible default task configuration and some level of build awareness. A plugin architecture allows you to break up large configurations down into more focused ones which are likely to be comman across multiple projects. [Published plugins](https://www.npmjs.com/search?q=lineman) can be installed using npm: From fa3351bbd72e58db4f5dac1d2316d852b485b9de Mon Sep 17 00:00:00 2001 From: iampeterbanjo Date: Mon, 21 Sep 2015 11:41:43 +0100 Subject: [PATCH 8/8] Use unordered lists for formatting --- .../scaffolding/lineman/getting-started.md | 48 ++++++++++++++----- 1 file changed, 37 insertions(+), 11 deletions(-) diff --git a/chapters/scaffolding/lineman/getting-started.md b/chapters/scaffolding/lineman/getting-started.md index 4979971..4ad6ef9 100644 --- a/chapters/scaffolding/lineman/getting-started.md +++ b/chapters/scaffolding/lineman/getting-started.md @@ -96,17 +96,43 @@ Lineman can be integrated with your Ruby on Rails project via the `lineman-rails In your Ruby on Rails app: -1. Add this to your Gemfile: `gem 'rails-lineman'` -2. Tell the gem where to look for Lineman: `config.rails_lineman.lineman_project_location = "my/app"`. You can also set an environment variable called **LINEMAN_PROJECT_LOCATION** -3. Include Lineman's CSS & JavaScript: `<%= stylesheet_link_tag "lineman/app" %> <%= javascript_include_tag "lineman/app" %>` -4. Boot your Rails server: `$ bundle exec rails s` -5. When you deploy, Lineman assets will be built and included: `$ rake assets:precompile` +- Add this to your Gemfile: +``` bash +gem 'rails-lineman' +``` +- Tell the gem where to look for Lineman: +``` bash +config.rails_lineman.lineman_project_location = "my/app" +``` +You can also set an environment variable called **LINEMAN_PROJECT_LOCATION** +- Include Lineman's CSS & JavaScript: +``` erb +<%= stylesheet_link_tag "lineman/app" %> +<%= javascript_include_tag "lineman/app" %> +``` +- Boot your Rails server: +``` bash +$ bundle exec rails s +``` +- When you deploy, Lineman assets will be built and included: +``` bash +$ rake assets:precompile +``` In your Lineman app: -1. Install Lineman's Rails plugin. This will setup some additional static routes and enable the API proxy: `$ npm install --save-dev lineman-rails` -2. Start your Lineman server: `$ lineman run` -3. During development use Lineman's server: `$ open http://localhost:8000` +- Install Lineman's Rails plugin. This will setup some additional static routes and enable the API proxy: +``` bash +$ npm install --save-dev lineman-rails +``` +- Start your Lineman server: +``` bash +$ lineman run +``` +- During development use Lineman's server: +``` bash +$ open http://localhost:8000 +``` ## Lineman plugins Lineman aims to be focused on sensible default task configuration and some level of build awareness. A plugin architecture allows you to break up large configurations down into more focused ones which are likely to be comman across multiple projects. [Published plugins](https://www.npmjs.com/search?q=lineman) can be installed using npm: @@ -117,8 +143,8 @@ $ npm install --save-dev lineman-jade ## Creating plugins A Lineman plugin has the following requirments: -1. Every plugin's name must start with "lineman-" in order to be discovered and auto-loaded by Lineman. -2. The plugin's `package.json` file should declare "lineman" as a peer dependency: +- Every plugin's name must start with "lineman-" in order to be discovered and auto-loaded by Lineman. +- The plugin's `package.json` file should declare "lineman" as a peer dependency: ``` js // package.json @@ -126,7 +152,7 @@ A Lineman plugin has the following requirments: "lineman": ">= 0.24.0" } ``` -3. Any grunt task modules or other runtime dependencies you need should be included in the "dependencies" object so that they will be installed and available to the end user. +- Any grunt task modules or other runtime dependencies you need should be included in the "dependencies" object so that they will be installed and available to the end user. A plugin file closely resembles the format of each project's `config/application` and `config/files` files. JavaScript and Coffeescript files under `config/plugins` will be automatically picked-up and run by Lineman and merged into your project configuration. An example of a plugin file is: