dm-npm

The tool for npm-module maniacs.

Description

• the module is under development
• This command line tool helps to fulfill the daily jobs you have to do when working with npm modules.
• This module with give you a structure for your npm modules that is the same in every of your nmp modules. that enables reusability and eases collaborative work on a npm module
• Documention in progress.

Participate

• i really apreciate if you give me feedback.
• i am always open to improve my workflow.
• so open issues for errors or new features/tasks here dm-npm issues
• note: i am relativly new to npm module development, so forgive me flaws and comment or open issues for improvements
• i will definetly use this tool for while, because i want to write a lot of npm modules, so stay tuned and watch out for updates
• look at the todos to see what will be done

Shorcuts

dmn
dm-npm

Environment

• tested on ubuntu 14.04 with node 0.11.11 and 0.12.0

Installation

npm install dm-npm -g

Prerequisits

• for publishing a module you have to create accounts on:
  • npmjs.com
  • github.com

How to start

A short use case.

Init a new npm module (with dm-npm style)

• online
  • create github repository
• local

# install dm-npm
npm install dm-npm -g

# clone the repository
git clone git@github.com:your_user_name/fooBar.git     

# cd into the repository
cd fooBar

# initialize the module
dmn init

# publish the module directly
dmn publish

Now you have a new running module with a task example, which you can run programmatically via:

var fooBarExample = require("fooBar").example;
fooBarExample();

or globally in the command line via

fooBar example

For testing the task you can run

fooBar test example

There are synchronous and asynchronous tests. explanation later

The created module will have the following structure:

module directory structure

.
|--bin/
   |--dm-fooBar
   |--gdm-fooBar
|--node_modules/
   |--co/
   |--colors/
   |--dm-npm/
   |--shelljs/
|--tasks/
   |--example/
      |--test/
         |--test.js
      |--index.js
|--global.js
|--ideas.md
|--index.js
|--package.json
|--README.md
|--todo.md

global.js vs index.js

• in global.js the task-hooks for the command line usage are collected
• in index.js the task-hooks for programmatically usage are collected

create your first task

• run fooBar taskAdd
  • this command will prompt you for
    • the task name (give it the name baz for test purpose)
    • the task aliases (give it the alias bz for test purpose)
    • the task description
  • then the command will
    • create a task in the directory tasks with your given task name (tasks/baz/index.js). here you can find
      • the yieldable function startAsync which has to be called with yield
      • the normal function start which is used to wire up the task in the global.js
    • create a entry in the README.md under the point tasks
    • create a hook for the task in the global.js
    • create a hook for the task in the index.js
    • create a test suite (tasks/baz/test/test.js) which you can run via fooBar test baz
    • open the task with your $EDITOR home environment variable (i am coding with vim and it will work for me)
• globally usage: presuming you named your task baz and gave it the alias bz you are now able to run
  • fooBar bz or fooBar baz and should see the outcoming
  • the output should look like start baz
• programmatically usage:
  • after publishing your module you can use your method in other modules

var fooBarBaz = require("fooBar").baz;
fooBarBaz();

• README.md: if you look into the README.md of the project you will see a added documentation section for the task baz
• global.js: if you look into the global.js you see a added swith for your task bar, which makes it globally accessable
• index.js: if you look into the index.js you see a added switch for your task bar, which makes it programmatically accessable

use the some basic tasks from dm-npm for your module

After inititalizing the project you get some basic tasks a npm developer needs for a project out of the box. these tasks are:

# opens help. if you have installed markdown and lynx you can browse it with terminal ;-)
fooBar

# add a task to your module
fooBar taskAdd

# open a prompt for your module where you can start the tasks existent in your module, open the markdown files of your project or edit the config file of your project
fooBar prompt

# opens the todo.md of fooBar and lets you write something in there
fooBar todo

# add a idea to the ideas.md via command line (creates the ideas.md if not exitent)
fooBar idea

# todo: bumps the version of the project (including git commit)
fooBar bumpVersion

# publishes fooBar (includes bumpVersion etc)
fooBar publish

# todo: add a config file for fooBar
fooBar configFileAdd

# todo: install fooBar globally
fooBar installGlobal
 
# todo: links your global fooBar installation locally to your development directory: this is very nifty, because you dont have to reinstall the tool globally on every change
fooBar linkLocal

# todo: reinitializes the project. keeps .git, README.md, todo.md, ideas.md
fooBar reinit

The tasks marked with todo are currently available when you cd into your module and run dmn bumpVersion or dmn publish etc. they will all get some improvements and some new features.

Generators

Most of the tasks here use the yield style and assume the code is contained within a generator function. For example you can use co for that. This style requires ES6 generators and has to be enabled in node 0.11.x or greater via the --harmony flag.

Task List Documentation

• bumpVersion todo
• configFileAdd todo
• idea
• init
• installGlobal todo
• linkConfigFiles
• linkLocal todo
• linkNodeModules todo
• prompt
• publish
• publishFolder
• reinit todo
• reinstall todo
• taskAdd todo
• todo

Tasks

configGet

• Returns json from the config file

configGet global usage

dmn [configGet|cg]

configGet programmatically usage

var configGet = require("dm-npm").configGet;
var configGetResult = configGet.start();

configGet steps

configGet features

configGet config

{
    "configGet": {
    }
}

configEdit

• Opens the config file for editing

configEdit global usage

dmn [configEdit|ce]

configEdit programmatically usage

var configEdit = require("dm-npm").configEdit;
var configEditResult = configEdit.start();

configEdit steps

configEdit features

configEdit config

{
    "configEdit": {
    }
}

help

• provides the README.md of the module (if markdown and lynx are installed with terminal browsing ;-))

help global usage

dmn [help|-help|h|-h]

help programmatically usage

var help = require("dm-npm").help;
var helpResult = help.start();

help steps

help features

help config

{
    "help": {
    }
}

getCommonTasks

• provides the dm-npm tasks that can be used by every dm-npm module

getCommonTasks global usage

dmn [getCommonTasks|gct]

getCommonTasks programmatically usage

var getCommonTasks = require("dm-npm").getCommonTasks;
var getCommonTasksResult = getCommonTasks.start();

getCommonTasks steps

getCommonTasks features

getCommonTasks config

{
    "getCommonTasks": {
    }
}

init

• initiate a new npm module with the dm-npm flavor

global usage

dmn [init|-init|i|-i]

programmatically usage

init steps

1. User Input:

• module name: for example fooBar
• module Shortcut: for example fb

2. add .gitignore from template
3. add package.json from template
4. add index.js from template

• this file is the entrypoint for programatically usage

5. add global.js from template

• this file is the entrypoint for usage from the command line

6. add README.md from template
7. add todo.md from template
8. add test directory
9. add bin directory

• the binary file for global usage
• this one is important. adds the following alias, you can use from command line
  • fooBar # runs your module
  • fb # alias for fooBar
  • gfb # cd into your module
  • fbg # cd into your module

10. add tasks directory with test task
11. run npm install

• install the dependencies

12. run task create local link

After running that command your module is globally installed and you have the following features enabled for your module.

features

global (run from everywhere)

• fb # opens cat's the readme.md
• fb prompt # opens a prompt with all added tasks
• fb todo # opens the todo.md file with vim
• fb idea # asks for a idea you have for your project and adds it to the end of ideas.md. creates ideas.md if not existent
• [gfb|fbg] # cd into the module directory (no need to create aliases)

local (run from npm module directory)

• gfb && dmn task add // adds a tasks in dir tasks and makes it programmatically and globally available

publish

command

dmn [publish|-publish]

publish steps

1. get/create root path (.git-repository with package.json for npm)
2. get git status
3. switch git status
   • a) if git status (2) says nothing to commit, abort task (path clean)
   • b) if git status (2) says there is something to commit (go on)
4. commit current changes
5. bump version in package.json (see task bump version)
6. commit the bump Version change
7. push commits
8. tag new version
9. push tags
10. npm publish

publishFolder

• publishes all npm modules in a given folder

global usage

dmn [publishFolder|pubFol|pf|-pf]

programmatically usage (todo)

publishFolder steps

1. searches for publishFolder.path in ~/dm-npm.json for usage as default value
2. asks for the directory including the npm-modules destined to publish

• dirctories starting with _ (underscore) will be ignored

3. then, a loop will run the task publish for every directory included in the prompted path

linkConfigFiles

• links files from given directory into home directory

global usage

dmn [linkConfigFiles|lc]

programmatically usage

linkConfigFile steps

1. search for ~/.dm-npm.json and get linkConfigFiles.path as default value

• for example ~/dotfiles/npm-modules-config

2. prompt user for directory where the npm module files are placed
3. links the src to the home directory

• adds a . to the beginning of the filename and soft links it in the home directory
• ie: ln -s ~/dotfiles/npm-modules-config/fb.json ~/.fb.json

idea

• add ideas to the npm-module via shell (ideas will be added to ideas.md)
• examples

dmn idea // 

prompt

• prompts for execution of the existent tasks of npm module
• examples

dmn prompt // 

todo

• opens the todo.md file of the npm module
• examples

dmn todo // 

Config

• you can place a .dm-npm.json file in your home directory (~/.dm-npm.json)
• the following things are allowed at the moment

{
  "publishFolder": {
    "path": "~/code/dm"
  }
}

Testing

• i am not really done here ;-)

  npm test

Links

• npm access problem
• node global acces problem
• creating and publishing a node-js module
• npm run script environment
• tilde vs caret

Lessons Learned