csxs

What is this? A command line tool written in node.js for creating, compiling, packaging, debugging, and deploying extensions for Adobe® Creative Suite®. It's easy as to use and as it is powerful.

It is designed to solve workflow problems and constraints that come from using Flash Builder. As an added bonus, projects created with this tool contain boilerplate to resolve strange platform bugs we've encountered.

We used to it to build our Creative Market Photoshop Extension.

Advantages

• Use any editor you want!
• All project settings live in a single JSON file (documentation).
• Automated signing, deploys to S3, changelog management, git tagging, etc.
• Open source!

Requirements

• Build and Install Node.js
• Install NPM: curl http://npmjs.org/install.sh | sh
• Install csxs: npm install -g csxs

Getting Started

To create a new project, make an empty folder and use the "create" target to set up an empty project that's ready to go for development. To compile a debug version and add it to Photoshop, use the "debug" target.

# create a folder for a project
$ mkdir my-extension
$ cd my-extension

# create the project & start it
$ csxs create
$ csxs debug --launch

More information about building and publishing the extension will be listed in the "README.md" created with the project.

Project Structure

Configuration

All project settings live in "csxs.json" (guide). The settings in this file are synthesized to various XML files needed by the Flex Compiler and Signing Tool during the build process.

Folders

assets/	Icons for the panel and Adobe Extension Manager.
changes/	A directory containing individual changelog files, by version.
src/	Extension source code.
README.md	Getting started guide.
HISTORY.md	An aggregated list of changes generated by the "changelogs" target.
csxs.json	All project settings (in lieu of *.xml files).

Advanced Topics

Conditional Compilation

The following conditional compilation variables are automatically provided:

• CONFIG::version (string)
• CONFIG::debug (boolean)
• CONFIG::release (boolean)

Adding Custom Variables

Custom variables can be set by adding them to the "properties" object in "csxs.json". The values must be scalar. The one exception to this is if you want different values for debug builds and release builds. In this case, provide an object with two properties: "debug" and "release".

{
	"properties": {
		"url": {
			"debug": "http://sandbox.domain.com",
			"release": "http://domain.com"
		}
	}
}

Editing XML and MXI Files

XML and MXI files in the project are populated by the properties in "csxs.json" at build time. For complicated extensions, it might be necessary to make changes in these files. Any of the files in the "src/" folder can be safely edited. Template variables should follow handlebars syntax.

Automated S3 Deployment

Automated deployment of releases is done with the "publish" target. The build tool will compile a release build, package it as a *.zxp installer, and place it on S3 (along with a history of changes). All that's needed is an S3 account. See the documentation on the "s3" property to see how to add S3 configuration.

$ csxs publish

Deployed Files & Folders

changes/	Contains changelogs by version and a "master.txt" file (an aggregated list).
update.xml	Update info read by Adobe Extension Manager.
update.json	Update info in JSON format.
MyExtension.zxp	Latest version.
MyExtension.0.0.1.zxp	Archival version.

Automated Git Tagging

When running "publish", HEAD will be tagged with the version being deployed for reference. It is the equivalent of running:

$ git tag vX.X.X
$ git push origin --tags

Multiple Configurations

In the rare case that a project needs multiple configurations (i.e. multiple "csxs.json" files), you can specify the configuration file to use from the command line with the --config option.

$ csxs target --config=csxs_free.json
$ csxs target --config=csxs_paid.json

If this option is not provided, "csxs.json" will be read by default.

Footnotes

• 100% compatible with Mac OSX. Windows support is partial / spotty right now.
• If your project needs host adapters, they have to be extracted manually from Extension Builder (Adobe Forums thread).

License

Copyright © 2013 Creative Market

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyrights & Trademarks

The included "bin/ucf.jar" binary is copyright Adobe Systems Incorporated. The license can be found here. "Creative Suite" is a registered trademark of Adobe Systems Incorporated.