bit3/packer

This package is abandoned and no longer maintained. No replacement package was suggested.

Pack JS and CSS distribution with compile and minify support using the Assetic framework.

1.0 2014-04-03 07:47 UTC

Requires

• php: >=5.4
• kriswallsmith/assetic: ~1.1
• symfony/console: 2.4.*
• symfony/process: 2.4.*
• symfony/yaml: 2.4.*

MIT

• Tristan Lins

• javascript
• css

README

Add a package.yml to your repository and run the pack command.

Configuration

There are 3 configuration files.

The default.yml contains the default configuration.

The package.yml contains the package configuration, for your project. This one should be added to your repository.

The package.local.yml contains system / environment specific configuration (like paths to binaries). This one should not be added to your repository.

They will be loaded in this order and merged into each other. That means in general you package.yml contains the package information, while the package.local.yml contains paths to the binaries on your system.

Convenience: If you want to provide a package.local.yml that works for your team, for example all use the same system environment, put a package.local.yml.dist with system environment specific settings into you repository. You should not overcharge the package.yml with system environment specific settings!

Watching modifications

A lot compilers like sass/compass have a "watch" feature. But when using chains of compilers and minifiers, this is not easy to automating. Use the --watch (-w) flag will cause the packer to watch for modifications on the packages.

If you using importing (like the sass @import rule) or embedding (like the cssembed filter), you may want to specify which files must be watched?! Simply add a watch block into your package.yml, directly after the files block and specify the files or directories to watch.

packages:
	dist/package.css:
		files:
			# remind that all files here will be watched anyway
			- reset.css
		watch:
			# watch a single file
			- src/file_to_watch.css
			# directories are also allowed
			- assets/images/
			# or watch all watches from another package
			- @dist/other_package.css

Deployment

Using the "watch" feature is nice for local development, but what if you must compile local and push to a remote host? This may necessary when your website is placed on a shared host, without shell/compiler support.

Using deployment is realy easy, first you need to define your deployment commands:

deploy:
	- notify-send "Build %file% finished"

And use the --deploy option to your command: pack --deploy

After each package, the deployment will be executed. The placeholder %file% is replaced with the pathname of the package, %package% with the name of the package and %deploy% with the deployment target (which is default by default).

Output example

$ pack dist/package.css --deploy
parse configuration
+ load .../bit3/packer/src/default.yml
+ load package.yml
+ load package.local.yml

build package dist/package.css
* build collection from dist/package.css
  ~ filters:
    - cssrewrite [Assetic\Filter\CssRewriteFilter]
  + add local file src/reset.css
* write file dist/package.css

deploy to notify
  * exec notify-send "Build dist/package.css finished"

Deployment targets

Having one deployment target is nice for simple setups, but what if you need to deploy to multiple places depending on what you currently work on? One possible usage scenario is a preview and production deployment.

When you add the deploy section, all commands will be added to the default deployment targets. To define multiple deployment targets, group the commands inside of the deploy section.

deploy:
	preview:
		- scp %file% [e-mail]:/var/www/vhosts/preview.example.com/assets/
	production:
		- scp %file% [e-mail]:/var/www/vhosts/example.com/assets/

Now you have two deployment targets which can be used particular by pack --deploy preview and pack --deploy production, or together with a single pack --deploy preview --deploy production.

Hint There is simply no difference between

deploy:
	- <cmd>

and

deploy:
	default:
		- <cmd>

Hint It is also possible to mix grouped and non-grouped commands:

deploy:
	- <cmd 1>
	production:
		- <cmd 2>

which is exactly the same as:

deploy:
	default:
		- <cmd 1>
	production:
		- <cmd 2>

Warning If you want to deploy specific packages (pack dist/only_this_package.css) and deploy these to the default deployment target (pack --deploy), the package name may be assumed as deployment target, if you just use pack --deploy dist/only_this_package.css. Just add default after --deploy: pack --deploy default dist/only_this_package.css or simply switch the parameters: pack dist/only_this_package.css --deploy.

package.yml reference

packages:
	dist/package.css:
		filters: [cssrewrite]
		files:
			# add a string
			- |
				/*
				 * (c) <copyright holders>
				 */

			# add a static file
			- src/reset.css

			# add a file with filters
			- [src/base.scss, [scss]]
		watch:
			# watch a file
			- src/file.css

			# watch a directory
			- assets/images/

			# watch files from another package
			- @dist/other_package.css

	dist/package.min.css:
		# extend another package
		extends: dist/package.css

		# remind that this will overwrite the filters, not extend
		filters: [cssrewrite, yui-css]

	vendors:
		# this is a virtual package, that will not be build
		virtual: true
		files:
			- framework.css

	dist/package.with-vendors.css:
		# this will merge two packages into one
		files:
			# an @<name> will referencing another package,
			# so you can merge and mixin multiple packages
			- @dist/package.css
			- @vendors