develop-a-package.md

Develop A Package

---

You can follow the steps to develop a package using spm.

$ spm --version
3.6.0

Make sure that [email protected] is installed.

init

$ mkdir now && cd now
$ spm init

Creating a spm package:
[?] Package name: (now)
[?] Version: (1.0.0)
[?] Description: hello world
[?] Author: pigcan <[email protected]>

Initialize a spm package Succeccfully!

Then you have a package named now.

Install dependencies

Install default devDependencies first.

$ spm install

We need moment as a dependency which can be found here.

$ spm install moment --save

Code and Debug

Edit index.js as follow, just like nodejs.

// require module in spm.dependencies
var moment = require('moment');

// require relative file in you project
// var util = require('./util');

var now = moment().format('MMMM Do YYYY, h:mm:ss a');
module.exports = now;

Then edit examples/index.md:

# Demo

---

## Normal usage

````javascript
var now = require('../index');
console.log(now);
````

Run spm doc to start a documentation service at 127.0.0.1:8000 .

$ spm doc

Open http://127.0.0.1:8000/examples/ in browser to see the result.

Except using three ` in Markdown file, you can also use four ` to wrap your code.

It is a special rule that make your code highlighted and would be inserted to document page as a script block so they can be excuted at the same time. That is very useful for debugging your demo and writing a beautiful documentation both.

If you want to insert a iframe in your demo, make your code to iframe type.

````iframe:600
I am in a iframe of 600px high
````

If you don't want to debug your code by spm doc, you can try spm-webpack-server to debug CommonJS modules in development.

Add Test Case

Edit test file at tests/now-spec.js. We introduce a default assert solution expect.js.

var expect = require('expect.js');
var now = require('../index');

describe('now', function() {

  it('normal usage', function() {
    expect(now).to.be.a('string');  // add this
  });

});

See tests result.

$ spm test

You can also open http://127.0.0.1:8000/tests/runner.html in browser.

Publish

Now you have a great package having wonderful function and complete tests case, you can publish the package to spmjs.io.

$ spm publish

You should run spm login first to get permission, otherwise it would propmt the authorization problem.

$ spm login

username is the name of your github account, and authkey can be found at http://spmjs.io/account after signing in.

The package now is published by me, of cause. You should change other name and retry.

Documentation

spmjs.io can host your package's documentation. What all you need to do is editing README.md and examples folder, preview it by spm doc watch, then publish it to spmjs.io.

$ spm doc publish

The documentation url is http://docs.spmjs.io/{{name}}/ for latest version and http://docs.spmjs.io/{{name}}/{{version}}/ for each versions.

For example, http://docs.spmjs.io/now/.

Build

$ spm build

This command will build the files indicated by spm.main and spm.output field to dist folder. The spm.build would be executed as arguments.

The default build result is a package which could be deployed at cdn. Then you can use it .For example.

In your html

<script>
  var now = require('now');
  console.log(now);
</script>

In your project package.json

{
    "name": "Project-Name",
    "spm": {
        "output": ["index.js"],
        "dependencies": {
            "now": "1.0.0"
        }
    },
    "devDependencies": {
        "spm": "~3.6.0"
    },
    "scripts": {
        "build": "spm build"
    }
}

Congratulation

Now you learn how to develop a package using spm, welcome to publish your packages here!