Stage-devtools
Devtools for convenient Stage.js development.
Requirement
- Nodejs v0.10.26+
- Bower v1.3+
- Nodemon v1.1+
- Git v1.8+
- GraphicsMagick v1.3.19+
We have prepared a development environment guide for you, please consult it before continue.
Install
npm install -g stage-devtools
This will give you a globally available stagejs
command in cli. You can check it with the version and help options on:
stagejs -V
stagejs -h, --help
Usage
Check environment
stagejs env
Pay attention to the result of this command, you might need to install additional programs required by the dev toolset.
Initialize new project
stagejs init
This will download the latest Stage.js starter kit for you and prepare the development environment.
Trouble Shoot A: If somehow bower install
or npm install
fails during the init process, you can go to the /implementation
(bower) and /tools
(npm) folder to run them yourself. (e.g npm needs sudo, or bower got some lock/racing condition or network connection problem...)
Trouble Shoot B: If the init cmd report something like this:
...
npm ERR! code EACCES
...
There is a high chance that you've installed your Node.js using the root user. This is a bad way of having Node.js on your development machine (you can do this on a production server though). It is highly recommended that you install Node.js through NVM, else, you will need to type sudo npm install
every time instead of npm install
and the stagejs init
, stagejs update
command will not work for you during the npm
involved steps.
Uninstall your Node.js and use NVM instead if you are having the npm permission problem. Don't forget to set your default node
version after installing specific Node.js version through nvm
.
Last resort: Use this one if you've removed Node.js and using npm
through NVM installed node instances
sudo chown -R `whoami` ~/.npm
This should clear the permission issue once-n-for-all.
Trouble Shoot C: if the init cmd report something like this:
...
gyp ERR! ...
npm WARN optional dep failed, continuing canvas@x.x.x
You can safely ignore these kind of warning messages during stagejs init
.
Create main
stagejs create main
This will create a new main.js
from our suggested code template.
Create contexts
stagejs create --fileonly context <name>
This will create an empty context script and its mockup template.
Create views
stagejs create --fileonly view <your view name in dotted notation>
This is to create an empty named view script and its mockup template. e.g a.b.c
means to create both js/a/b/c.js
and static/template/a/b/c.html
.
Create editors & validators
stagejs create --fileonly editor <name>
stagejs create validator <name>
Editors will also have their mockup template created.
Create widgets & plugins
stagejs create --fileonly widget <name>
stagejs create plugin <name>
Widgets will also have their mockup template created as.
Create/Refresh theme
(You can also update existing theme with this cmd)
//create, refresh
stagejs theme <your theme name>
//list available themes currently in your project.
stagejs theme ls
This will create a new theme for you to develop with, which extends from the default theme package. If the theme already exists, it will refresh it. (With css-sprite generation included)
Note: Refresh a theme will not copy the original default theme package over again, so if you want to keep that part updated as well you will have to do it manually.
Tip: use -h
to see more options with this command.
Manage 3rd-party libraries
If you want to use 3rd-party libraries not bundled with the framework distribution, you can use the stagejs lib
command:
//update, install/uninstall and other normal `bower` commands.
stagejs lib update [lib, ...]
stagejs lib install [lib, ...]
stagejs lib uninstall <lib, ...>
stagejs lib ls
//use, unuse a lib in your project
stagejs lib use <lib> [js file]
stagejs lib unuse <lib>
Without the use
, unuse
sub-commands the lib
command works just like the bower
cli.
The use
, unuse
will manipulate the .html
file pointed by the -i, --index
option, adding/removing 3rd-party library files to the <script>
tags.
Tip: stagejs lib use <lib> [js file]
will automatically consult the library's bower.json
metadata to figure out which javascript is the main one and use that for you. If the command replies with that it can't find the main javascript then you can specify the relative path of the javascript you want in the library through the 2nd parameter.
Update project
stagejs update [-e, --edge]
This will update bower.json
and then maintain the bower managed packages (it will do the same to npm packages). It will also update the default theme package and tools. If you put --edge
option into the command, it will also fetch and replace stage.js
, stage.min.js
and dependencies.min.js
with the latest edge build from the Stage.js project repository.
By default, the update
command will only install missing libraries & packages indicated by the updated bower.json
and package.json
. (Yes if the version number of a package changes, the install process will update it)
Build project
(single config file - dist.js, doesn't require app server to be running)
stagejs build [--dist <path to your deploy folder>] [--config <config name>]
This will build your project into production ready package, including js combine/minification, folder merge/creation and file copying.
Limitation: The build command requires a config file to present (defaults on tools/build/config.dist.js
) and the build process will not refresh your project themes, so make sure you've done that before invoking build.
Tip: use -h
to see more options with this command.
Start dev app server
(single config/setup file - profile.js)
stagejs serve [--port <port number>] [--profile <profile name>]
//or
stagejs serve [port]
This will start the development server for you. It includes CORS, HTTP(s) Request Forwarding, WebSocket, Background Tasks, RESTful API and DB/Store. It also includes code change monitors for you to easily watch *.less
theme file and *.html
template file changes. Config to this server will be read in from its profile, you can enable/disable its features there and add more customized stuff if needs be.
Limitation: There is no group/role based authorization yet, only ACL based authentication atm.
Create routes
(+RESTful APIs based on Expressjs4)
stagejs create router <your router name in dotted notation>
Create middlewares
stagejs create middleware <name>
Limitation: It requires more effort than just creating a middleware definition file from this command. Given that the sequence of middleware loading does affect your application, and some of the middleware requires additional configure to setup, you will have to manually edit the middleware stack in the server profile before your new middleware can take effect in the app server.
Create tasks (TBI)
stagejs create task <your task name>
This will create an empty background task definiton stub for you.
Export project code
stagejs export
This will package your project into exported.tar.gz
according to tools/build/config.export.js
.
Import project code
stagejs import [exported package file] [-o, --override]
This will copy the content of wanted code package over to your current project. Use the -o or --override
flag to force overriding existing files during the import process.
The .stagejsrc file
This is the optional env file for stagejs
cli, which normally contains the following information: (in JSON format)
{
"implementation": "./implementation",
"tools": "./tools"
}
For it to take effect, simply put it under the current working directory where you invoke the stagejs
command.
Contribute
Clone the project:
git clone https://github.com/bluekvirus/Stage-devtools.git
Create your own patch/contrib branch:
git checkout -b <your patch/contrib branch name>
Install node packages required for development:
npm install
Add or modify commands in /cmd
folder and have them tested through:
touch [Stage-devtools folder]/cmd/[cmd].js
node [Stage-devtools folder]/cli.js [cmd]
So, a commmand named abc.js
under /cmd
can be invoked like this:
node [Stage-devtools folder]/cli.js abc [rest of the arguments]
For a minimum new command implementation consult /cmd/env.js
or /cmd/init.js
.
Live Tests
mkdir TestProject
cd TestProject
node [Stage-devtools folder]/cli.js [cmd] <arguments>
For example, if your development folder is like this,
- /Stage-devtools
- /TestProject
Then the live test line above becomes
cd TestProject
node ../Stage-devtools/cli.js [cmd] <arguments>
Make sure you test the commands in the /TestProject
before committing your changes.
You will need to add an issue then make a pull-request to submit your modifications.
Distribute
(You do NOT need to do this if contributing, I'll take care of this after getting the pull requests)
Update README.md
(optional), CHANGELOG.md
and package.json
before releasing new versions through npm publish
.
License
Copyright 2014 - 2017 Tim Lauv. Under the MIT License.