On a high-level, to create a new package, you'll need to:

1. Create a new project, with its own tests, build, releases, etc.
2. Integrate that project's tests and documentation into canjs/canjs.

An official package is:

• In a repository under the CanJS organization.
• Listed and documented under the Ecosystem Collection.
• Tested in the canjs/canjs integration suite.
• Published on npm as can-<name> (with a few exceptions).

Unofficial packages can be maintained however you choose, but to maximize your project’s:

• Compatibility — useful in as many development environments as possible (Browserify, StealJS, Webpack, etc.)
• Discoverability — other developers can find it
• Contribute-ability — other developers can contribute to it

…we suggest following the documentation on this page.

We’ve broken this down into the following sections:

• Create a new project
• Set up Continuous Integration
• Write documentation
• Integrate build with CanJS
• Integrate tests with CanJS
• Integrate documentation with CanJS

Create a new project

Follow the DoneJS plugin guide with the following changes:

1. Pick a package name that has can in the name.

2. When the donejs add plugin generator asks for “Project main folder”, use .

3. List canjs in your package.json’s keywords.

4. Update the code to match the File organization and responsibilities section. There are a few changes to make:

• Change everything to CommonJS. Use require('module-name') instead of import 'module-name'.
• Use tabs instead of spaces.
• Use dashes instead of underscores in generated filenames.

Set up Continuous Integration

Adding Greenkeeper

Adding Travis

Make sure to activate CI on the source package by including a .tavis.yml file in the project root.

# An example configuration
language: node_js
# Load nodejs 6.x
node_js:
  - "6"
# Allow ability to run Firefox headless for Testee
before_install:
  - "export DISPLAY=:99.0"
  - "sh -e /etc/init.d/xvfb start"

Write documentation

In this guide, project repo refers to the repository that will be added to the CanJS.com site.

Source Repo Documentation

Create a markdown file in the docs folder of project repo and name it after the project.

cd can-fixture
mkdir ./docs
touch ./docs/can-fixture.md

Note: The location of the document files is discussed here as a common use case. Keep in mind that bit-docs does not expect documents in any folder. Only that documents use the correct tag syntax.

Source Repo Documentation Tags

In order to include the source project's documentation on the CanJS site, the main document file requires some tags.

@module {*} <PACKAGE_NAME>
@parent <CANJS_PARENT_TARGET>
@package <PATH_TO_PACKAGE.JSON>

• PACKAGE_NAME: is the project name, which should match the name property in the source project's package.json.
• CANJS_PARENT_TARGET: is the name of the target area in CanJS. For example, if the module is a part of the "Ecosystem", then the value for @parent would be can-ecosystem. If the target is "Legacy" then the value is can-legacy.
• PATH_TO_PACKAGE.JSON: is a relative path from the main document file for the project repo. Considering the following structure...

- docs
 - can-fixture.md
- src
- package.json

If can-fixture.md is the main document, then the relative path to the package.json is ../package.json.

This would result in a main document file that looked something like this

@module {function} can-fixture
@parent can-ecosystem
@package ../package.json

> Documentation goes here

Integrate build with CanJS

The project repo needs to be added to the CanJS project.

npm install <PACKAGE_NAME> --save

Once the project is added as a dependency, the source project's main file needs to be included in the CanJS project.

In the root directory of the project, locate the appropriate JavaScript file.

- /canjs
 - can.js
 - ecosystem.js
 - legacy.js

Open the desired file and require the source project. For infrastructure and core packages, use the can.js file.

require('<SOURCE_PACKAGE_NAME>');

For example, in CanJS, we have included the can-fixture project.

Run node build.js to build CanJS. You should be able to to use dist/global/can.all.js to show examples with your code.

If you can't you might need to:

• Add your pacakge's export to can-namespace like:

  var namespace = require("can-namespace");
  
  var myCoolThing = {};
  module.exports = can.myCoolThing = myCoolThing
  

• Make sure to exclude any 3rd-party projects from canjs/build.js like:

  var ignoreModuleNamesStartingWith = [
    "jquery",
    "SOME_OTHER_LIBRARY"
    ...
  ]
  

  And train them to be loaded globally on the window like:

  var exportsMap = {
      "jquery": "jQuery",
      "SOME_OTHER_LIBRARY": "SomeOtherLibrary"
      ...
  };
  

  And make sure your package's modules are able to run without the library:

  var namespace = require("can-namespace");
  var SomeOtherLibrary = require("SOME_OTHER_LIBRARY");
  
  var myCoolThing;
  if(SomeOtherLibrary) {
      myCoolThing = SomeOtherLibrary({});
  }
  
  module.exports = can.myCoolThing = myCoolThing
  

Integrate tests with CanJS

Open the main test file in the CanJS repo, located at canjs/test/test.js.

Note: The tests in this file will run in dev mode and production mode. If your tests should only run in dev mode, add them to canjs/test/test-dev-only.js.

Require the project repo's test main test file in the appropriate area. For example, if the project repo will go in "Legacy" area of the site, then add it to the "Legacy" section of the test file.

For example, we have added the can-fixture tests to the test file.

Run npm run test to run tests, verify the project does not adversely affect the test suite.

Integrate documentation with CanJS

Open the can-api.md doc file, located at ./docs/can-canjs/can-api.md.

Again, add any necessary markup to the correct section (related to the target parent; legacy for legacy, etc).

Follow this helpful markdown template:

- **[<PACKAGE_NAME>]** <small><%<PACKAGE_NAME>.package.version%></small> <PACKAGE_DESCRIPTION>
  - `npm install <PACKAGE_NAME> --save`
  - <a class="github-button" href="<PROJECT_GITHUB_URL>">Star</a>

• PACKAGE_NAME: The project name, which should match the name property in the source project's package.json.
• PACKAGE_DESCRIPTION: short description of project, can match the description property in source project's package.json.
• PROJECT_GITHUB_URL: The Github url. Not the git path but the path to the html site.

For example, we have added the markup for can-fixtures.

Run npm run document to build the documentation site. Read more on the Improving the Docs & Site page.