From b3be70a3368749ffac419825fa1474e43f940328 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=84=E5=AF=82?= Date: Fri, 29 May 2015 11:59:01 +0800 Subject: [PATCH] chore: add 3.4 en documents to en folder, add 3.4 zh-cn documents to zh-cn folder --- README.md | 29 -- en/css-and-template.md | 87 ++++++ en/develop-a-package.md | 198 +++++++++++++ en/difference-from-2.x.md | 21 ++ en/getting-started.md | 67 +++++ en/package.json.md | 80 ++++++ en/spm-commands.md | 151 ++++++++++ misc/release-3.6.md | 46 --- misc/upgrade-to-3.6.md | 57 ---- project/build-global.md | 123 -------- project/configuration.md | 271 ------------------ project/debug.md | 110 ------- project/get-started.md | 97 ------- setup.md | 62 ---- zh-cn/README.md | 17 ++ zh-cn/SUMMARY.md | 19 ++ zh-cn/build/README.md | 31 ++ zh-cn/commands/README.md | 83 ++++++ .../develop-package/README.md | 85 ++++-- zh-cn/develop-package/include-css.md | 25 ++ .../develop-package/include-package-files.md | 22 ++ zh-cn/develop-package/include-template.md | 14 + .../migrate-opensource-package.md | 6 + zh-cn/develop-package/migrate-to-spm3.md | 7 + zh-cn/develop-package/package-type.md | 3 + zh-cn/develop-project/README.md | 136 +++++++++ zh-cn/develop-project/modes.md | 38 +++ zh-cn/develop-project/spm-server.md | 99 +++++++ zh-cn/develop-project/strategy.md | 46 +++ zh-cn/develop-project/using-bootstrap.md | 6 + zh-cn/environment.md | 61 ++++ zh-cn/get-started.md | 66 +++++ zh-cn/package.json/README.md | 77 +++++ zh-cn/package.json/buildArgs.md | 87 ++++++ zh-cn/registry/README.md | 31 ++ zh-cn/registry/private.md | 31 ++ 36 files changed, 1576 insertions(+), 813 deletions(-) delete mode 100644 README.md create mode 100644 en/css-and-template.md create mode 100644 en/develop-a-package.md create mode 100644 en/difference-from-2.x.md create mode 100644 en/getting-started.md create mode 100644 en/package.json.md create mode 100644 en/spm-commands.md delete mode 100644 misc/release-3.6.md delete mode 100644 misc/upgrade-to-3.6.md delete mode 100644 project/build-global.md delete mode 100644 project/configuration.md delete mode 100644 project/debug.md delete mode 100644 project/get-started.md delete mode 100644 setup.md create mode 100644 zh-cn/README.md create mode 100644 zh-cn/SUMMARY.md create mode 100644 zh-cn/build/README.md create mode 100644 zh-cn/commands/README.md rename package/get-started.md => zh-cn/develop-package/README.md (54%) create mode 100644 zh-cn/develop-package/include-css.md create mode 100644 zh-cn/develop-package/include-package-files.md create mode 100644 zh-cn/develop-package/include-template.md create mode 100644 zh-cn/develop-package/migrate-opensource-package.md create mode 100644 zh-cn/develop-package/migrate-to-spm3.md create mode 100644 zh-cn/develop-package/package-type.md create mode 100644 zh-cn/develop-project/README.md create mode 100644 zh-cn/develop-project/modes.md create mode 100644 zh-cn/develop-project/spm-server.md create mode 100644 zh-cn/develop-project/strategy.md create mode 100644 zh-cn/develop-project/using-bootstrap.md create mode 100644 zh-cn/environment.md create mode 100644 zh-cn/get-started.md create mode 100644 zh-cn/package.json/README.md create mode 100644 zh-cn/package.json/buildArgs.md create mode 100644 zh-cn/registry/README.md create mode 100644 zh-cn/registry/private.md diff --git a/README.md b/README.md deleted file mode 100644 index 8afd8cc..0000000 --- a/README.md +++ /dev/null @@ -1,29 +0,0 @@ - -# docs - -阅读文档前，请确保 spm 的版本 >= 3.6 。 - -```bash -$ spm -v -3.6.0 -``` - -## 目录 - -- [环境配置](./setup.md)：如何在 mac 和 windows 下安装 node 和 spm -- 组件开发 - - [组件入门](./package/get-started.md)：包含脚手架、依赖安装、本地调试、测试用例、登录、发布 -- 项目开发 - - [项目入门](./project/get-started.md)：如何快速开发春节倒计时的需求 - - [调试](./project/debug.md)：包含本地调试、livereload、weinre、线上调试 - - [配置项](./project/configuration.md)：详解构建配置 - - [指定依赖](./project/build-global.md)：开发指定依赖 jQuery 项目 -- 其他 - - [升级到 3.6](./misc/upgrade-to-3.6.md)：升级注意事项 - - [发布 3.6](./misc/release-3.6.md) - -## 相关 - -- [案例](https://github.com/spmjs/examples/tree/spm-webpack) - - diff --git a/en/css-and-template.md b/en/css-and-template.md new file mode 100644 index 0000000..6fa5613 --- /dev/null +++ b/en/css-and-template.md @@ -0,0 +1,87 @@ +# Handle css and template + +--- + +Css and html template are significant parts in front-end development, and spm is just good for it. + +## Css + +The spm package could be a pure css package, use `main` and `output` to specify endpoint files. + +For Example, there is a `main-style` package for our site layout: + +``` +button.css +tip.css +index.css +package.json +``` + +```json +{ + "name": "main-style", + "version": "1.0.0", + "spm": { + "dependencies": { + "normalize.css": "3.0.1" + }, + "main": "index.css" + } +} +``` + +Simply import files and other packages by a standard `@import`. + +``` +/* index.css */ +@import url('http://github.com/normalize.css'); + +@import url('http://github.com/button.css'); +@import url('http://github.com/tip.css'); +``` + +[alice-button](https://github.com/aliceui/button) is a nice example as well. + +You can also require css package in js file, just like js package but without exports. + +``` +require('main-style'); +var moment = require('moment'); +``` + +spm will use [import-style](http://spmjs.io/package/import-style) to import css package's content after building. + + +## Template + +Fisrtly, write your template in file, named it as `*.html` or `*.tpl` or `*.handlebars`. + +```html + +
+ {{name}} + {{content}} +
+``` + +Then require it in js file. + +```js +var Handlebars = require('handlebars'); +var source = require('./defalut.tpl'); // string content of defalut.tpl + +var template = Handlebars.compile(source); // compile it with your compiler +var result = template({ + name: 'alex', + content: 'content' +}); +``` + +If the extension is `.handlebars`, `spm build` will precompile it and import [handlebars-runtime](http://spmjs.io/package/handlebars-runtime) automaticly for better perfermance, just similar with css's procedure. + + +## Precompile language + +People prefer a lot precompile languages both for css and template, such as [less](http://lesscss.org/), [scss](http://sass-lang.com/), [mustache](https://github.com/janl/mustache.js), [Hogan.js](https://github.com/twitter/hogan.js), [doT](https://github.com/olado/doT) and etc. + +Consider [spm.scripts](/documentation/package.json#fields) in package.json for precompileing procedure. diff --git a/en/develop-a-package.md b/en/develop-a-package.md new file mode 100644 index 0000000..f0ce573 --- /dev/null +++ b/en/develop-a-package.md @@ -0,0 +1,198 @@ +# Develop A Package + +--- + +You can follow the steps to develop a package using [spm](https://github.com/spmjs/spm). + +``` +$ spm --version +3.x.x +``` + +Make sure that spm@3.x is installed. + +## init + +```bash +$ mkdir now +$ cd now +$ spm init +``` + +``` +Creating a spm package: +[?] Package name: (now) +[?] Version: (1.0.0) +[?] Description: +[?] Author: afc163 + +Initialize a spm package Succeccfully! +``` + +Then you have a package named `now`. + +## Install dependencies + +Install default devDependencies first. + +```bash +$ spm install +``` + +We need [moment](http://momentjs.com) as a dependency which can be found [here](http://spmjs.io/package/moment). + +```bash +$ spm install moment --save +``` + +## Code and Debug + +Edit `index.js` as follow, just like nodejs. + +```javascript +// 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` . + +```bash +$ spm doc +``` + +Open [http://127.0.0.1:8000/examples/](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 [seajs-wrap](https://github.com/seajs/seajs-wrap) or [spm-server](https://github.com/spmjs/spm-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](http://spmjs.io/package/expect.js). + +```javascript +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. + +```bash +$ spm test +``` + +You can also open [http://127.0.0.1:8000/tests/runner.html](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](http://spmjs.io/). + +```bash +$ spm publish +``` + +You should run `spm login` first to get permission, otherwise it would propmt the authorization problem. + +```bash +$ 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. + +```bash +$ spm doc publish +``` + +The documentation url is `http://spmjs.io/docs/{{name}}/` for latest version and `http://spmjs.io/docs/{{name}}/{{version}}/` for each versions. + +For example, http://spmjs.io/docs/now/. + +## Build + +```bash +$ spm build +``` + +This command will build the files indicated by `spm.main` and `spm.output` field to `dist` folder. The `spm.buildArgs` would be executed as arguments. + +The default build result is a package which could be deployed at cdn. Then you can use it by using [Sea.js](https://github.com/seajs/seajs/), [seajs@2.2.1](https://raw.githubusercontent.com/seajs/seajs/2.2.1/dist/sea.js) for example. + + +```html + + + +``` + +And We strongly recommend building a [standalone](/documentation/spm-commands#spm-build) package by adding an argument. + +```bash +$ spm build --include standalone +``` + +```html + + +``` + +## Congratulation + +Now you learn how to develop a package using spm, welcome to publish your packages here! diff --git a/en/difference-from-2.x.md b/en/difference-from-2.x.md new file mode 100644 index 0000000..47f8aa9 --- /dev/null +++ b/en/difference-from-2.x.md @@ -0,0 +1,21 @@ +# Difference From spm@2.x + +--- + +[spm@3.x](https://github.com/spmjs/spm/tree/master) is new version of [spm@2.x](https://github.com/spmjs/spm/tree/2.x), we have a collection of updates now. + +- [spmjs.org](https://spmjs.org) is package service for spm@2.x, now is [spmjs.io](http://spmjs.io) which is prettier and easier to [deploy in your company](https://github.com/spmjs/spmjs.io/). + +- Change spm profile from `~/.spm/spmrc` to `~/.spm/spmrc-3x`. + +- `family` is removed from package.json. + +- `spm.alias` is replaced by `spm.dependencies` now. + +- `spm doc`, `spm init`, `spm build`, `spm test` are integrated to spm commands. + +- [docs.spmjs.org](http://docs.spmjs.org) is old documentation for spm@2.x. + +- No need to build first before publish, the package only contains source code. Building is needed just before using in your website. + +- [迁移 spm2 到 spm3](https://github.com/spmjs/spm/wiki/%E8%BF%81%E7%A7%BB-spm2-%E7%9A%84%E6%A8%A1%E5%9D%97%E5%88%B0-spm3) diff --git a/en/getting-started.md b/en/getting-started.md new file mode 100644 index 0000000..5bd5399 --- /dev/null +++ b/en/getting-started.md @@ -0,0 +1,67 @@ +# Getting Started + +--- + +## Introduction + +[spm](https://github.com/spmjs/spm) is a powerful and integrated static package manager designed for browser-side solutions including JavaScript, CSS and template. + +[![](https://i.alipayobjects.com/i/localhost/png/201404/2YQxOTYoFp.png)](https://github.com/spmjs/spm) + +All packages in `spmjs.io` should be written in CommonJS, having a complete lifecycle management via [spm](https://github.com/spmjs/spm), including the following features: + +- Initialization +- Dependencies Management +- Local Development +- Publishing on [spmjs.io](http://spmjs.io) +- Test Runner +- Documentation Site Generator and Host +- Build + +[spmjs.io](http://spmjs.io/) is packages management service for spm. You can browse for packages you need, or publish your package here. + +`spmjs.io` is a new version of [spmjs.org](https://spmjs.org/) which is based on the old `spm@2.x`. + +## Installation + +```bash +$ npm install spm -g +``` + +> `npm install spm@2.x -g` for old spm2. + +## Basic Usage + +Init a spm package. + +```bash +$ mkdir example +$ cd example +$ spm init +``` + +Install dependencies. + +```bash +$ spm install jquery --save +$ spm install moment@2.6.0 --save +``` + +Publish the package to [spmjs.io](http://spmjs.io/) + +```bash +$ spm publish +``` + +> You should run `spm login` first to get permission. The `authkey` will be displayed at http://spmjs.io/account after signing in. + +Add `.spmignore` for ignoring useless files to avoid oversize of package. + +## Contribution + +Anyone is welcome to contribute by the following ways. + +- [Bug reports](https://github.com/spmjs/spm/issues) +- [Feature requests](https://github.com/spmjs/spm/issues) +- [Pull requests](https://github.com/spmjs/spm/pulls) +- Promote spm on your social network. diff --git a/en/package.json.md b/en/package.json.md new file mode 100644 index 0000000..b85d4d7 --- /dev/null +++ b/en/package.json.md @@ -0,0 +1,80 @@ +# Package.json + +--- + +`spm` use the exactly same file `package.json` as `npm` to describe a package, which shares most fileds, except an extra `spm` filed for containing some custom attributes. + +### Fields + +Field | Description | +------------ | ------------- | +name* | name of the package in lowercase, use a `-` or `.` as a separator between words +version* | semantic versioning like 1.0.0 +description | a brief description of the package +keywords | an array of keywords +homepage | url of the package's website +author | author of the package: `Hsiaoming Yang ` or `{ "name": "Hsiaoming Yang", "email": "me@lepture.com" }` +maintainers | an array of maintainers, just like author +repository | specify the place where the code is hosted. `{ "type": "git", "url": "http://github.com/isaacs/npm.git" }` +bugs | the url to the package's issue tracker and / or the email address to which issues should be reported. +license | license +**spm*** | +spm.main | the only entry point of the package, default `index.js`, or could be set to `index.css` for a css-only package +spm.output | an array of other files needed to be output +spm.dependencies | specify dependencies relation of the package +spm.devDependencies | specify dependencies relation of the package in developing situation +spm.tests | specify all test files, support glob patterns: `tests/*-spec.js` +spm.buildArgs | specify the cli arguments for `spm build` +spm.ignore | an array of ignore files in package, same function as `.spmignore` +spm.scripts | like npm.scripts, handle around some spm commands, it support `prebuild`, `postbuild`, `preinstall`, `postinstall`, `prepublish`, `postpublish`. + + +### A basic example + +```json +{ + "name": "arale-calendar", + "version": "1.1.0", + "description": "Calendar widget.", + "keywords": [ + "widget", + "month", + "datepicker" + ], + "author": "Hsiaoming Yang ", + "maintainers": [ + "hotoo ", + "shengyan " + ], + "homepage": "http://aralejs.org/calendar/", + "repository": { + "type": "git", + "url": "https://github.com/aralejs/calendar.git" + }, + "bugs": { + "url": "https://github.com/aralejs/calendar/issues" + }, + "license": "MIT", + "spm": { + "main": "calendar.js", + "dependencies": { + "jquery": "1.7.2", + "moment": "2.6.0", + "arale-base": "1.1.0", + "arale-position": "1.1.0", + "arale-iframe-shim": "1.1.0", + "handlebars": "1.3.0", + "arale-widget": "1.2.0" + }, + "devDependencies": { + "expect.js": "0.3.1" + }, + "tests": "tests/*-spec.js", + "ignore": ["dist"], + "buildArgs": "--ignore jquery", + "scripts": { + "prepublish": "lessc index.less index.css" + } + } +} +``` diff --git a/en/spm-commands.md b/en/spm-commands.md new file mode 100644 index 0000000..42bddf7 --- /dev/null +++ b/en/spm-commands.md @@ -0,0 +1,151 @@ +# Spm Commands + +--- + +`spm` have a collection of commands for package lifecycle management. + +There is a simple list of them, and you can type `spm [command] -h` to learn more details. + +![](https://t.alipayobjects.com/images/T1Rj8cXhl5XXXXXXXX.png) + +#### spm init +Init a package from template. + +#### spm login +Login for getting permission. + +#### spm install [name[@version]] +Install dependencies and engines to local folder. + +#### spm publish +Publish a package. + +#### spm unpublish [name[@version]] +Unpublish a package. + +#### spm info [name[@version]] +Show information by package name. + +#### spm search [query] +Search packages. + +#### spm ls +Show the dependencies tree of the package. + +#### spm doc [build|watch|publish] +Documentation management toolkit. + +* spm doc + + Alias for `spm doc watch`. + +* spm doc watch + + Build and start a watching server of demo site at http://127.0.0.1:8000 . + +* spm doc build + + Build a demo package to `_site` folder. + +* spm doc publish + + Publish `_site` folder to [spmjs.io](http://spmjs.io/). The demo site url is `http://spmjs.io/docs/{{package-name}}` + +#### spm test + +Run test case in phantomjs. + +#### spm build + +Build package for browser. + +##### -O [dir] + + output directory, default: `dist` + +##### -o [file] `since 3.4.0+` + + output single file. + + ``` + spm build index.js -o build.js + ``` + +##### -s --standalone `since 3.4.0+` + + Build a standalone package that could be used in script tag way without any loader, + equal with `--include standalone`. + +##### --sea [mode] `since 3.4.0+` + + Build a [CMD](https://github.com/cmdjs/specification/blob/master/draft/module.md) package that could be loaded by [Sea.js](https://github.com/seajs/seajs), equal with `--include [relative|all]`. + + - relative `default` + + Only contain relative dependencies. Absolute dependencies should be online so that it can be loaded dynamicly. + ```js + // would load the-module, and load the-module's dependencies dynamicly. + seajs.use('the-module'); + ``` + + - all + + Contain relative and absolute dependencies. + ```js + // only load the-module, all dependencies will be packed in the-module.js. + seajs.use('the-module'); + +##### --umd `since 3.4.0+` + + Build a umd package for both loader and global usage. + +##### --include [include] `Deprecated` + + Determine which files will be included, optional: `relative`, `all`, `standalone`, `umd`. + + Deprecated, use --standalone, --umd [umd] and --sea instead. + + - relative `default` + + Only contain relative dependencies. Absolute dependencies should be online so that it can be loaded dynamicly. + ```js + // would load the-module, and load the-module's dependencies dynamicly. + seajs.use('the-module'); + ``` + + - all + + Contain relative and absolute dependencies. + ```js + // only load the-module, all dependencies will be packed in the-module.js. + seajs.use('the-module'); + + ``` + + - standalone + + Build a standalone package that could be used in script tag way without any loader. + ```html + + ``` + + - umd + + Build a umd package for both loader and global usage. + + +##### --ignore [ignore] + + Determine which id will not be transported. + +##### --skip [skip] + + Determine which id will not be parsed when analyse. + +##### --global [jquery:$,underscore:\_] + + Replace package name to global variable, format `jquery:$,underscore:_`. + +##### --idleading [idleading] + + Prefix of module name, default: `{{name}}/{{version}}`. diff --git a/misc/release-3.6.md b/misc/release-3.6.md deleted file mode 100644 index db349b4..0000000 --- a/misc/release-3.6.md +++ /dev/null @@ -1,46 +0,0 @@ - -# SPM 3.6 发布 - -大家好， - -这个版本的性能、稳定性均有显著提升。而由于改动比较大，所以跳了一个版本，直接发 3.6 。 - -![](https://t.alipayobjects.com/images/T1x5RfXi4nXXXXXXXX.png) - -主要有以下改动： - -**(1) 基于 webpack 重新实现了 build** - -- 性能更快：比如钉钉的项目从之前的 `200s` 缩短到 `52s`，经过配置后最后到 `38s` -- 功能更强大：比如公用包和文件的提取，动态依赖、循环引用、node 模块补丁等，详见 [配置项](https://github.com/spmjs/docs/blob/master/project/configuration.md) 和 [案例](https://github.com/spmjs/examples/tree/spm-webpack) -- 扩展性更好：比如这样配置 `"loader": {".js":"+./foo"}`，即可对所有 js 文件用本地的 `foo.js` 进行额外处理，[Demo](https://github.com/spmjs/examples/tree/spm-webpack/custom-loader) - -**(2) doc, server 和 test 基于 build 实现** - -之前是基于中间件实现的，和 build 的流方式是两套。所以，调整方案之后： - -- 稳定性更好：不会存在调试通过后，构建出来的代码有问题的情况 -- 维护成本更低：仅需维护一套方案 -- 文档静态化：doc 生成的文档终于静态化了，可部署到任意地方 - -**此外，还有一些其他的变更点：** - -- 内置 server ：不再需要额外安装命令就可进行项目调试了 -- [spm-sea](https://github.com/spmjs/spm-sea)：spm 只内置 standalone 方式的打包，cmd 方式抽取成 spm-sea，不再内置 -- css 包规则变更：`@import 'http://github.com/~foo'` 表示 foo 模块，`@import 'http://github.com/foo'` 表示 foo 文件，[讨论](https://github.com/spmjs/spm-sea/issues/2) - -**文档教程：** -- [升级到 3.6](https://github.com/spmjs/docs/blob/master/misc/upgrade-to-3.6.md) -- [例子](https://github.com/spmjs/examples/tree/spm-webpack#examples) -- [项目入门](https://github.com/spmjs/docs/blob/master/project/get-started.md) -- [组件入门](https://github.com/spmjs/docs/blob/master/package/get-started.md) - -**感谢：** -- webpack - -最后，有升级或迁移到 spm 的想法，都可以找 @云谦 聊下。 - --- - -云谦 - diff --git a/misc/upgrade-to-3.6.md b/misc/upgrade-to-3.6.md deleted file mode 100644 index 8f66618..0000000 --- a/misc/upgrade-to-3.6.md +++ /dev/null @@ -1,57 +0,0 @@ - -# 升级到 3.6 - -## 规则变更 - -- css import 规则变更，@import 'http://github.com/~foo' 表示 foo 模块，@import 'http://github.com/foo' 表示 foo 文件，[详](https://github.com/spmjs/spm-sea/issues/2) - -比如： - -```css -@import 'http://github.com/alice-base'; -``` - -要改成 ： - -```css -@import 'http://github.com/~alice-base'; -``` - - -## 组件开发 - -主要是 markdown 文件写法变更： - -- 只能使用 commonjs 写法，不再支持 cmd 的方式 -- 不能 require 相对文件，只能 require 包 - -比如： - -```js -seajs.use('./index', 'jquery', function(Dialog, $) { - new Dialog($('#el')); -}); -``` - -要修改成： - -```js -var Dialog = require('dialog'); -var $ = require('jquery'); - -new Dialog($('#el')); -``` - -## 项目开发 - -主要是配置项变更： - -- build 相关的配置项全部移到 build 属性下 -- output 中不支持写 css 文件，需通过 `extractCSS` 属性来解决，[Demo](https://github.com/spmjs/examples/tree/spm-webpack/react) -- 更多详见：[配置项](../project/configuration.md) - -另外： - -- 项目调试使用 `spm server` 而不是 `spm-server`，详见：[调试](../project/debug.md) -- spm 仅内置支持 standalone 的打包方式，seajs 用户请使用 [spm-sea](https://github.com/spmjs/spm-sea) - diff --git a/project/build-global.md b/project/build-global.md deleted file mode 100644 index 6deef79..0000000 --- a/project/build-global.md +++ /dev/null @@ -1,123 +0,0 @@ -# 指定依赖 - -package.json 中 `spm.build.global` 指定依赖，他们不会被解析，但会被替换为 window 下的全局变量。 - -比如： - -```js -var $ = require('jquery'); -``` - -配置 `"global":{"jquery":"jQuery"}` 后被构建成： - -```js -var $ = window['jQuery']; -``` - -你可以利用 global 避免打包一些基础模块，比如 `jQuery` `underscore.js` 。 - -## 开发指定依赖 jQuery 项目 - - -### 创建目录和文件 -``` -$ mkdir build-global && cd build-global -$ touch index.html index.js package.json -``` -> Windows 用户请创建 build-global 目录，进入 build-global目录创建 `index.html` 、 `index.js` `package.json` 文件 - -### 准备HTML -在 index.html 写上基本的页面结构和样式： - -```html - - - - - 使用 spm 开发指定依赖 jQuery 的项目 - - - -
- - - - -``` - -### 声明依赖 - -在 `package.json` 中写入： - -```js -{ - "spm": { - "build": { - "global": { - "jquery": "jQuery" - } - } - } -} -``` - -### 下载 jquery.min.js 至 lib 目录 -[https://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.3/jquery.min.js](https://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.3/jquery.min.js) - -此时目录结构为： -``` -└── lib/ -│ └── jquery.min.js -├── index.html -├── index.js -└── package.json -``` -### 编写 index.js - -``` -var $ = require('jquery'); -$(function (){ - $('#box').hide(333).show(333); -}) -``` - -### 调试代码 - -调试开发模式下的 CommonJS 代码： -``` -$ spm server -``` -打开 [http://127.0.0.1:8000/](http://127.0.0.1:8000/) 预览效果 - -### 构建项目 -开发完毕，一行命令构建： - -``` -$ spm build index.js index.html -``` - -构建后的目录结构为： -``` -└── dist/ - ├── index.html - └── index.js -└── lib/ -│ └── jquery.min.js -├── index.html -├── index.js -└── package.json -``` - -dist/index.js 文件内容为: - -```js -!function(r){function o(e){if(t[e])return t[e].exports;var n=t[e]={exports:{},id:e,loaded:!1};return r[e].call(n.exports,n,n.exports,o),n.loaded=!0,n.exports}var t={};return o.m=r,o.c=t,o.p="",o(0)}([function(r,o,t){var e=t(1);e(function(){e("#box").hide(333).show(333)})},function(r,o,t){r.exports=jQuery}]); -``` - -[查看更多配置项](https://github.com/nimojs/docs/blob/master/project/configuration.md) \ No newline at end of file diff --git a/project/configuration.md b/project/configuration.md deleted file mode 100644 index 1e3a212..0000000 --- a/project/configuration.md +++ /dev/null @@ -1,271 +0,0 @@ - -# 配置项 - -> spm 的项目可通过修改 package.json 来配置构建参数。 - -所有参数： - -```js -{ - "name": "", - "version": "", - - "spm": { - - "build": { - // -- 依赖解析 - // 指定不解析的模块或文件 - "global": { - "react": "React", - "./a": "AAA" - }, - // 开启或禁用 node 模块的 polyfills - "node": { - "global": false - }, - - // -- 性能 - // 提取依赖为 vendor.js - "vendor": ["jquery", "underscore"], - // 提取公共 chunk 为 common.js - "common": true, - "base64": {}, - - // -- 语言类 - "babel": {}, - "uglify": {}, - "autoprefixer": {}, - "less": {}, - "coffee": {}, - "jsx": {}, - "handlebars": {}, - - // -- 输出 - "dest": "./build", - "hash": true, - // 提取入口 js 文件依赖链中的 CSS chunk，输出和入口文件同名的 css 文件 - "extractCSS": true, - // 输出的包名 - "library": "", - // this, umd, common, amd, var 等等 - "libraryTarget": "", - // 等同于 libraryTarget: umd, library: Foo - "umd": "Foo", - - // -- 扩展 - "loader": { - ".js": "+jsdc-babel" - }, - - // -- 调试 - "define": { - "DEBUG": false - } - }, - - "server": { - "devtool": "#eval", - "define": { - "DEBUG": false - } - }, - - "registry": "" - } -} -``` - -## build 配置 - -### global - -指定依赖，他们不会被解析，但会被替换为 window 下的全局变量。 - -比如： - -```js -var $ = require('jquery'); -``` - -配置 `"global":{"jquery":"jQuery"}` 后被构建成： - -```js -var $ = window['jQuery']; -``` - -[Demo](https://github.com/spmjs/examples/tree/master/build-global) - -### node - -配置是否引入 node 相关的补丁。 - -默认值： - -```js -{ - console: false, - process: true, - global: true, - Buffer: true, - __filename: "mock", - __dirname: "mock" -} -``` - -### vendor - -配置是否提取依赖包为 vendor.js，默认关闭。 - -比如：有一个页面 a 依赖了 jquery 和 underscore，配置 `"vendor": ["jquery"]`，则会输出 a.js (包含 underscore) 和 vendor.js (包含 jquery) 。 - -[Demo](https://github.com/spmjs/examples/tree/spm-webpack/common-pkg) - -### common - -配置是否提取公用 chunks，默认关闭。 - -比如：有两个页面 a 和 b，他们同时依赖了 c 。配置 `"common": true` 之后，会输出 a.js, b.js 和 common.js 。 - -[Demo](https://github.com/spmjs/examples/tree/spm-webpack/common-file) - -### base64 - -配置是否把图片和字体文件转成 base64 ，默认关闭。 - -举例： - -- `"base64": true`，全部转换 -- `"base64": {"limit":10000}`，只在文件大小小于 10kb 时转换 - -[Demo](https://github.com/spmjs/examples/tree/spm-webpack/base64) - -### babel - -指定 ES6 转换器 babel 的配置项，默认关闭。 - -[Demo](https://github.com/spmjs/examples/tree/spm-webpack/es6) - -注：如果要支持 ie8，一些特性需要额外载入 es5-shim + es5-sham 可以。 - -- http://babeljs.io/docs/usage/caveats/#internet-explorer - -### uglify - -配置 uglify 压缩器的选项。 - -默认值： - -```js -sourceMap: false, -output: { - ascii_only: true, - comments: false -} -``` - -### autoprefixer - -配置 autoprefixer 的选项。 - -### dest - -配置输出目录，默认为 `./dist` 。 - -比如： - - - `"dest": "./build"` - -### hash - -配置输出文件名是否带 hash 后缀。 - -比如： - -- `"hash": true` - -### extractCSS - -提取 js 入口文件依赖链上的所有 CSS 为同名 CSS 文件，默认关闭。 - -比如： - -- `"extractCSS": true` - -[Demo](https://github.com/spmjs/examples/tree/spm-webpack/react) - -### library - -如果配置了，则作为类库输出，library 为类库名，默认关闭。 - -### libraryTarget - -配置输出格式，默认 "var" 。可选 "var", "this", "commonjs", "commonjs2" "amd", "umd" - -### umd - -配置输出格式为 umd，并指定类库名。 - -比如：`"umd": "Foo"` 等同于 `"library": "Foo"` 和 `"libraryTarget": "umd"` - -### loader - -配置扩展 loader。 - -比如要对 js 文件做额外处理，处理的文件是 ./loader.js，那么配置： - -```js -"loader": { - ".js": "+./loader" -} -``` - -比如： - -- `"loader": {".js": "+./loader"}`，对 js 文件用 .loader 做额外处理 -- `"loader": {".js": "+./loader$"}`，对 js 文件用 .loader 做预处理 -- `"loader": {".js": "./loader"}`，对 js 文件只用 .loader 进行处理 -- `"loader": {".js": "-jsx2"}`，不对 js 文件进行 jsx 处理 - -[Demo](https://github.com/spmjs/examples/tree/spm-webpack/custom-loader) - -### define - -定义环境变量，和 "server" 下的 "define" 配合使用，可区分开发和生产环境。 - -比如： - -```js -"build": { - "define": {"DEBUG":false} -}, -"server": { - "define": {"DEBUG":true} -} -``` - -然后代码里： - -```js -if (DEBUG) { - console.log('debug mode'); -} else { - console.log('production mode'); -} -``` - -这样就可以在调试环境下输出 `debug mode`，在生产环境下输出 `production mode` 。 - -[Demo](https://github.com/spmjs/examples/tree/spm-webpack/define) - -## server 配置 - -### devtool - -默认是 `"devtool": "#sourcemap"` 。 - -## scripts 配置 - -## registry 配置 - -强制指定源，比如 `"registry": "http://private.registry/"` - diff --git a/project/debug.md b/project/debug.md deleted file mode 100644 index 853dec9..0000000 --- a/project/debug.md +++ /dev/null @@ -1,110 +0,0 @@ - -# 项目调试 - -SPM3 一个较大的改变是源码书写规范从 CMD 变为 CommonJS ，带来的好处是和社区打通，更接近 nodejs 的开发体验。坏处是 CommonJS 的源码不能像 CMD 一样在浏览器里直接加载，从而影响线下的调试体验。 - -CommonJS 和 CMD 写法上最大的区别就是 `define(function(require, exports, module) {})` 的包裹，只要在调试阶段无缝的加入这个包裹，就可以比较方便的加载调试了。在 spm 3.6 之前的都是通过这个思路去解决的。 - -不过，这种方案有个比较大的问题，调试和构建方案不一致。所以潜在的会有调试通过但构建不通过的问题，并且维护上成本也比较高。所以在 spm 3.6 里，我们把调试方案基于构建来实现了。 - -有两个方案可供选择： - -1. `spm build --watch` -2. `spm server` - -第一种方案不需要开 server，适用于不方便开 server 的场景；第二种方案需要开 server ，功能更强大。 - -> @spm-server 老用户：spm server 和 spm-server 不是同一个东西。spm server 是 spm-webpack-server 。 - -下面主要介绍第二种方案。 - -## 本地调试 - -本地调试没啥好说的，就是进入到一个 spm3 的项目目录中，执行 `spm server`。 - -![](https://t.alipayobjects.com/images/T12PJfXktbXXXXXXXX.png) - -然后可以通过参数开启各种附加功能。 - -![](https://t.alipayobjects.com/images/T15OBfXgNsXXXXXXXX.png) - -### livereload - -通过 `spm server --livereload` 开启。 - -![](https://t.alipayobjects.com/images/T1rPReXjpvXXXXXXXX.png) - -这时 spm-server 会做两件事： - -1. 开启 livereload 服务器 -2. 访问 html 页面时会插入 livereload 脚本，用于和服务器通讯实时刷新页面 - -### weinre - -通过 `spm server --weinre` 开启。 - -![](https://t.alipayobjects.com/images/T1ij0eXcRmXXXXXXXX.png) - -和 livereload 一样，spm-server 会做两件事： - -1. 开启 weinre 服务器 -2. 访问 html 页面时会插入 weinre 脚本，用于和服务器通讯 - -然后就可以在 weinre 页面上看到当前绑定的设备了：(端口是 8989) - -![](https://t.alipayobjects.com/images/T15j4eXoNcXXXXXXXX.png) - -关于 weinre 的使用这里就不展开了，可以访问 [weinre 的官网文档](http://people.apache.org/~pmuellr/weinre/docs/latest/UserInterface.html) 来了解。 - -## 线上调试 - -线上调试主要是通过 anyproxy 实现。 - -```bash -## spm server 不直接依赖 anyproxy ，所以第一次使用前需要手动安装 -$ npm install anyproxy -g - -## 启动 spm server 和 (any)proxy -$ spm server --proxy -``` - -然后应该能看到下图的提示：(包含 GUI 和 HTTP 代理的端口) - -![](https://t.alipayobjects.com/images/T1nPNfXdlcXXXXXXXX.png) - -> 注意：第一次使用时应该会提示你安装根证书。 - -然后就是通过各种方式把请求配置到 HTTP 代理上去，比如 Chrome： - -### Chrome - -推荐使用扩展程序 [Proxy SwitchySharp](https://chrome.google.com/webstore/detail/proxy-switchysharp/dpplabbmogkhghncfbfdeeokoefdjegm?hl=zh-CN)，可以很方便地定制大力规则和情景模式。安装完成后，添加一个情景模式比如 spm： - -![](https://t.alipayobjects.com/images/T1jjVeXgpsXXXXXXXX.png) - -然后到切换到“切换规则”面板，启用规则切换，加入一条对 alipayobjects.com 的代理规则的配置： - -![](https://t.alipayobjects.com/images/T1h68eXd0cXXXXXXXX.png) - -> 根据项目的不同，这里可能需要加上你对应的开发环境的代理规则 - -OK，接下来选择开启 SwitchSharp 的“自动切换模式”，代理的配置就完成了： - -![](https://t.alipayobjects.com/images/T1i6VeXidsXXXXXXXX.png) - -然后访问 https://a.alipayobjects.com/ ，如果在页面上看到项目目录下的文件列表了，就说明本地环境启动成功了： - -![](https://t.alipayobjects.com/images/T1Hn4eXjJXXXXXXXXX.png) - -同时在 anyproxy 的监控页面也会看到一条请求记录： - -![](https://t.alipayobjects.com/images/T1.PVeXftnXXXXXXXX.png) - -### 移动端 - -1. 常规方法 - - ![](https://t.alipayobjects.com/images/T1eP0eXgdmXXXXXXXX.png) - -1. 代理 app，比如 Andriod 的 [ProxyDroid](https://play.google.com/store/apps/details?id=org.proxydroid) - diff --git a/project/get-started.md b/project/get-started.md deleted file mode 100644 index c2d039c..0000000 --- a/project/get-started.md +++ /dev/null @@ -1,97 +0,0 @@ - -# 项目入门 - -春节快要来了，工程师接到一个显示春节倒计时的需求。 - -工程师开始新建页面： - -```bash -$ mkdir countdown && cd countdown -$ touch index.html index.js -``` - -在 index.html 写上基本的页面结构和样式： - -```html - - - - - 新春倒计时 - - - -
- - - -``` - -工程师对这个需求进行了简单的系分，发现需要用到日期处理模块 [moment](http://spmjs.io/package/moment) 和一个 [util.format](http://spmjs.io/package/util) 格式化方法。这些模块在 [spmjs.io](http://spmjs.io) 上都可以找到，于是他通过 spm 直接安装模块到本地。 - -```bash -$ spm install moment util --save -``` - -依赖会保持到 package.json 中： - -```javascript -{ - "spm": { - "dependencies": { - "moment": "2.9.0", - "util": "0.10.3" - } - } -} -``` - -然后工程师就可以打开 index.js 进行 JS 应用的编写，文件使用 CommonJS 的格式，使用熟悉的 `require` 引入安装的依赖模块。 - -```javascript -var moment = require('moment'); -var util = require('util'); - -var newYear = moment([2016, 2, 8]); - -calculate(); -setInterval(calculate, 1000); - -function calculate() { - // 计算还差几天 - var now = moment(); - var diff = moment.duration(newYear.diff(now)); - - document.getElementById('count-down-text').innerHTML = - util.format( - '距 2016 年春节还有 %s 月 %s 天 %s 时 %s 分 %s 秒', - diff.months(), - diff.days(), - diff.hours(), - diff.minutes(), - diff.seconds() - ); -} -``` - -接着可以运行 `spm server` 启动服务，并访问 http://127.0.0.1:8000 就可以看到页面了。现在你可以直接修改 index.js 里的内容进行调试（甚至可以调试依赖模块）。 - -开发完毕，一行命令构建： - -``` -$ spm build index.js index.html -``` - -然后会在 `./dist` 目录下得到可运行的 index.js 和 index.html 文件。 - -实例查看：http://jsfiddle.net/j7d3Ld9x/ - -以上只是一个极简单的例子。spm 支持各类开发模式和前端语言包括 css、预编译样式语言、模板、React 等，支持通用模块的演示文档部署及内网的源部署方案，对前端的各类调试开发部署模式有很多探索和积淀。对于前端团队还是个人开发者都很友好，值得一试。 - diff --git a/setup.md b/setup.md deleted file mode 100644 index ed9f2b7..0000000 --- a/setup.md +++ /dev/null @@ -1,62 +0,0 @@ - -# 环境准备 - -## 安装 Node - -`Node.js` 支持 >= 0.10.29, 建议安装 >= 0.12.0 - -#### osx, linux 环境 - -```bash -$ git clone git@github.com:creationix/nvm.git ~/.nvm -$ source ~/.nvm/nvm.sh -# 安装 -$ nvm install v0.12.0 -# 显示当前本地安装的所有 Node.js -$ nvm ls -# 显示服务器所有可用的 Node.js -$ nvm ls-remote -# 本地可用的 Node.js 中使用 0.12.0 -$ nvm use 0.12.0 -# 设置每次启动默认版本 -$ nvm alias default 0.12.0 -``` - -### window 环境 - -这里假设大家都使用 `d:\git` 目录存放 git 项目。 - -```bash -$ d: -$ cd git -$ git clone git@github.com:nanjingboy/nvmw.git -# 设置 d:\git\nvmw 墓道到 PATH 环境变量 -$ set "PATH=d:\git\nvmw;%PATH%" -# 安装 -$ nvmw install 0.12.0 -# 显示当前本地安装的所有 Node.js -$ nvmw ls -# 显示服务器所有可用的 Node.js -$ nvmw ls-remote -# 本地可用的 Node.js 中使用 0.12.0 -$ nvmw use 0.12.0 -# 设置每次启动默认版本 -$ nvmw switch 0.12.0 -``` - -### node-gyp 编译环境配置 (可选) - -https://github.com/TooTallNate/node-gyp#installation - -## 安装 SPM - -```bash -$ npm i spm -g -``` - -如遇因网速原因导致的安装失败，可尝试使用 [cnpm](http://cnpmjs.org/) 的源加速安装。 - -```bash -$ npm i spm -g -r http://r.cnpmjs.org/ -``` - diff --git a/zh-cn/README.md b/zh-cn/README.md new file mode 100644 index 0000000..a2841b6 --- /dev/null +++ b/zh-cn/README.md @@ -0,0 +1,17 @@ +# SPM Handbook + +> 本书介绍如何用 [spm](https://github.com/spmjs/spm) 来开发组件和应用。 + +## 阅读 + +- [gitbook.io](http://sorrycc.gitbooks.io/spm-handbook/) + +## 名词解释 + +- `源`，详见 [源](registry/README.md) +- `组件`，指可以发布到源上的包，比如 [type 组件](http://spmjs.io/package/type) + +## 贡献 + +- [Bug reports](https://github.com/sorrycc/spm-handbook/issues) +- [Pull Requests](https://github.com/sorrycc/spm-handbook/pulls) diff --git a/zh-cn/SUMMARY.md b/zh-cn/SUMMARY.md new file mode 100644 index 0000000..9ccb1d3 --- /dev/null +++ b/zh-cn/SUMMARY.md @@ -0,0 +1,19 @@ +# Summary + +* [新手入门](get-started.md) +* [环境配置](environment.md) +* [package.json](package.json/README.md) + * [buildArgs](package.json/buildArgs.md) +* [组件开发](develop-package/README.md) + * [引入 CSS](develop-package/include-css.md) + * [引入模板](develop-package/include-template.md) + * [引入组件内部文件](develop-package/include-package-files.md) + * [迁移到 SPM3](develop-package/migrate-to-spm3.md) +* [项目开发](develop-project/README.md) + * [应用 Bootstrap](develop-project/using-bootstrap.md) + * [spm-server](develop-project/spm-server.md) + * [应对不同的项目类型](develop-project/strategy.md) +* [构建](build/README.md) +* [命令行](commands/README.md) +* [源](registry/README.md) + * [私有源](registry/private.md) diff --git a/zh-cn/build/README.md b/zh-cn/build/README.md new file mode 100644 index 0000000..f368ad1 --- /dev/null +++ b/zh-cn/build/README.md @@ -0,0 +1,31 @@ +# 构建 + +> 如果你不喜欢 cmd ，还可以自行写构建工具实现基于模块规范的输出 + +## `$ spm build` + +目前内置的 `spm build` 命令适用于组件和简单项目，功能包含： + +- 转换 commonjs 为 cmd 模块 ([gulp-transport](https://github.com/popomore/gulp-transport)) +- [spm-standalonify](https://github.com/spmjs/spm-standalonify) +- [uglifyjs](https://github.com/mishoo/UglifyJS2) +- [cssmin](https://github.com/jakubpawlowicz/clean-css) +- ... + +## 使用 + +```bash +$ spm build +``` + +## 扩展 + +对于有自定义需求的复杂项目，或者使用了预编译语言比如 less, coffee 的项目，则需自行基于 spm 提供的基础库实现构建流程。 + +附：[一个构建的例子](https://gist.github.com/sorrycc/809594fa344ad4a30a42) ，功能包含： + +- less, coffee 的预编译支持 +- pathmap 自定义输出路径 +- 自定义任务和流 +- autoprefixer +- ... diff --git a/zh-cn/commands/README.md b/zh-cn/commands/README.md new file mode 100644 index 0000000..1c6a867 --- /dev/null +++ b/zh-cn/commands/README.md @@ -0,0 +1,83 @@ + +# 命令行 + +`spm` 有一系列的命令来管理组件的生命周期。 + +下面是简单的列表，你可以执行 `spm help [command]` 查看详细信息。 + +![](http://gtms01.alicdn.com/tps/i1/TB1x4aMGFXXXXXLXVXXM_30QpXX-830-704.png) + +## spm init +通过模板生产组件的脚手架。 + +## spm login +登录，获取组件发布权限。 + +## spm install `[name[@version]]` +安装依赖到本地目录。 + +## spm publish +发布组件。 + +## spm unpublish `[name[@version]]` +撤销组件发布。 + +## spm tree +显示组件的依赖树。 + +## spm info `[name[@version]]` +通过名字查询组件信息。 + +## spm search `[query]` +搜索组件。 + +## spm test +通过 phantomjs 跑测试用例。 + +## spm doc `[build|watch|publish]` +文档管理工具集。 + +* spm doc build + + 构建文档到 `_site` 文件夹。 + +* spm doc watch + + 构建文档，并启动监听服务，地址是：http://127.0.0.1:8000 。 + +* spm doc publish + + 发布 `_site` 文件夹到 [spmjs.io](http://spmjs.io/) ， Demo url 是 `http://spmjs.io/docs/{{package-name}}` 。 + +## spm build +构建组件。 + +* -O [dir] `output directory, default: dist` +* --include [include] `determine which files will be included, optional: relative, all, standalone` + - relative `default` + + Only contain relative dependencies. Absolute dependencies should also be deployed so that it can run on Sea.js. + ```js + // would load abc, and abc's dependencies separately. + seajs.use('abc'); + ``` + - all + + Contain relative and absolute dependencies. + ```js + // only need to load abc. + seajs.use('abc'); + ``` + - standalone + + Build a standalone package that could be used in script tag way without any loader. + ```html + + ``` + +* --ignore [ignore] `determine which id will not be transported` +* --idleading [idleading] `prefix of module name, default: {{name}}/{{version}}` + +## spm completion +spm 命令自动完成脚本，可通过 `npm completion >> ~/.bashrc (or ~/.zshrc)` 安装。 + diff --git a/package/get-started.md b/zh-cn/develop-package/README.md similarity index 54% rename from package/get-started.md rename to zh-cn/develop-package/README.md index 42edf3d..7ede7bd 100644 --- a/package/get-started.md +++ b/zh-cn/develop-package/README.md @@ -1,9 +1,15 @@ - -# 组件入门 +# 组件开发 下面会一步步教你如何通过 [spm](https://github.com/spmjs/spm) 来开发一个组件。 -## 脚手架 +``` +$ spm -v +3.x.x +``` + +开始前，请确保安装了 spm@3.x 。 + +## init ```bash $ mkdir now @@ -11,7 +17,7 @@ $ cd now $ spm init ``` -```bash +``` Creating a spm package: [?] Package name: (now) [?] Version: (1.0.0) @@ -21,7 +27,7 @@ Creating a spm package: Initialize a spm package Succeccfully! ``` -这样，你就有了一个叫 now 的组件。 +这样，你就有了一个叫 `now` 的组件。 ## 安装依赖 @@ -31,15 +37,15 @@ Initialize a spm package Succeccfully! $ spm install ``` -然后我们需要 moment 依赖，这里 有他的详细信息。 +然后我们需要 [moment](http://momentjs.com) 依赖，[这里](http://spmjs.io/package/moment) 有他的详细信息。 -``` +```bash $ spm install moment --save ``` ## 开发 -编辑 index.js ，和在 nodejs 里一样： +编辑 `index.js` ，和在 nodejs 里一样： ```javascript var moment = require('moment'); @@ -58,17 +64,18 @@ module.exports = now; ## Normal usage ````javascript -var now = require('now'); -alert(now); // add this +seajs.use('index', function(now) { + alert(now); // add this +}); ```` ## 本地调试 -执行 `spm doc` 开启一个文档服务 127.0.0.1:8000 ： +执行 `spm doc watch` 开启一个文档服务 `127.0.0.1:8000` ： ```bash -$ spm doc +$ spm doc watch ``` 然后在浏览器里打开 [http://127.0.0.1:8000/examples/](http://127.0.0.1:8000/examples/) 即可看到结果。 @@ -77,7 +84,7 @@ $ spm doc 这是一条特殊规则，引用的代码首先会高亮显示，然后还会被插入一个 script 标签来同步执行。这一点非常有用，在调试 demo 的同时，还可以写出优雅的文档。 -如果想在 demo 中插入 iframe，需声明代码为 frame 类型： +如果想在 demo 中插入 iframe，需声明代码为 `frame` 类型： 
 ````iframe:600
@@ -85,7 +92,8 @@ I am in a iframe of 600px high
 ````
-如果不想用 `spm doc` 来调试代码，你还可以试试 spm server 来调试开发模式下的 CommonJS 代码。 + +> 如果不想用 `spm doc watch` 来调试代码，你还可以试试 [seajs-wrap](https://github.com/seajs/seajs-wrap) 或 [spm-server](https://github.com/spmjs/spm-server/) 来调试开发模式下的 `CommonJS` 代码。 ## 添加测试用例 @@ -110,12 +118,8 @@ describe('now', function() { $ spm test ``` -![](https://t.alipayobjects.com/images/T1GjRfXiBaXXXXXXXX.png) - 你也可以在浏览器里打开 [http://127.0.0.1:8000/tests/runner.html](http://127.0.0.1:8000/tests/runner.html) 查看结果。 -此外，还可以打开 `coverage/lcov-report/index.html` 查看测试覆盖率。 - ## 发布 现在你已拥有一个包含完整功能和完善测试用例的组件里，尝试把他发布到 [spmjs.io](http://spmjs.io/) 吧。 @@ -146,4 +150,49 @@ $ spm doc publish 比如：http://spmjs.io/docs/now/ 。 +## 构建 + +```bash +$ spm build +``` + +`spm build` 命令会构建 `spm.main` 和 `spm.output` 声明的文件到 `dist` 目录。`spm.buildArgs` 会作为参数传入。 + +默认的构建结果是可以被部署到 cdn 上的包。然后可以通过 [Sea.js](https://github.com/seajs/seajs/) 来引用他。比如：[seajs@2.2.1](https://raw.githubusercontent.com/seajs/seajs/2.2.1/dist/sea.js) 。 + + +```html + + + +``` + +你也可以添加参数来构建 [standalone](/documentation/spm-commands#spm-build) 的包。 + +```bash +$ spm build --include standalone +``` + +```html + + +``` + +## Congratulation + +至此，你应该已学会如何用 spm 开发一个组件，欢迎发布组件到这里！继续阅读： +* [引入 CSS](develop-package/include-css.md) +* [引入模板](develop-package/include-template.md) +* [引入组件内部文件](develop-package/include-pkg-files.md) diff --git a/zh-cn/develop-package/include-css.md b/zh-cn/develop-package/include-css.md new file mode 100644 index 0000000..817bd43 --- /dev/null +++ b/zh-cn/develop-package/include-css.md @@ -0,0 +1,25 @@ +# 引入 CSS + +> spmjs.io 上有不少 CSS 组件，比如 [normalize.css](http://spmjs.io/package/normalize.css) 和 `alice` 系列的 UI 组件。 + +和 JS 一样，你可以通过 `@import` 引入源上的 CSS 组件或本地的 CSS 文件。 + +```css +@import 'http://github.com/normalize.css'; +@import 'http://github.com/layout/layout.css'; + +body { + color: teal; + background: url('http://github.com/background-image.jpg'); +} +``` + +此外，spm 还提供了在 JS 里引入 CSS 的功能。 + +```javascript +@require('alice-box'); +@require('./theme/basic.css'); +``` + +> 通过这种方式引入 CSS 之后，构建时候会自动安装 [import-style](http://spmjs.io/package/import-style)，来加载 CSS 。 + diff --git a/zh-cn/develop-package/include-package-files.md b/zh-cn/develop-package/include-package-files.md new file mode 100644 index 0000000..f4bacd0 --- /dev/null +++ b/zh-cn/develop-package/include-package-files.md @@ -0,0 +1,22 @@ + +# 引入组件内部文件 + +在 spm 里，一个组件只允许有一个单一出口，这在某些情况下并不能完全满足需求。 + +比如 [bootstrap](http://spmjs.io/package/bootstrap) 组件，入口是 `js/bootstrap.js`，而如果要引入 CSS 文件，则需要： + +```css +@import 'http://github.com/bootstrap/css/bootstrap.css'; +``` + +或者你仅需要他的 tooltip 功能： + +```javascript +require('bootstrap/js/tooltip'); +``` + +比如 CSS 组件 [anima-ui](http://spmjs.io/package/anima-ui)，由很多模块组成，如果用户需要单独引入某一个模块： + +```css +@import 'http://github.com/anima-ui/build/util/flexbox.css'; +``` diff --git a/zh-cn/develop-package/include-template.md b/zh-cn/develop-package/include-template.md new file mode 100644 index 0000000..a05ded2 --- /dev/null +++ b/zh-cn/develop-package/include-template.md @@ -0,0 +1,14 @@ + +# 引入模板 + +SPM 支持在 JS 文件里直接引入两种模板： + +1. tpl +1. handlebars + +以 handlebars 为例，使用步骤为： + +1. 新建 `a.handlebars`，编辑模板内容 +1. 在 JS 文件里 `require("./a.handlebars");` +1. 调试(spm doc watch 或 spm-server) 和构建时会预编译 `a.handlebars` +1. 构建时如果发现有 require `handlebars` 文件，则会自动安装 `handlebars-runtime` 并保存到 `spm/dependencies` diff --git a/zh-cn/develop-package/migrate-opensource-package.md b/zh-cn/develop-package/migrate-opensource-package.md new file mode 100644 index 0000000..ce8b8c8 --- /dev/null +++ b/zh-cn/develop-package/migrate-opensource-package.md @@ -0,0 +1,6 @@ + +# 迁移业界优秀模块 + +详见：https://github.com/spmjs/spm/wiki/迁移业界优秀模块到-spmjs.io-并反推的简易教程 + + diff --git a/zh-cn/develop-package/migrate-to-spm3.md b/zh-cn/develop-package/migrate-to-spm3.md new file mode 100644 index 0000000..ea21b66 --- /dev/null +++ b/zh-cn/develop-package/migrate-to-spm3.md @@ -0,0 +1,7 @@ + +# 迁移 到 spm3 + +请根据组件类型进行选择： + +- [迁移 spm2 到 spm3](https://github.com/spmjs/spm/wiki/迁移-spm2-到-spm3) +- [迁移业界优秀模块到 spmjs.io 并反推的简易教程](https://github.com/spmjs/spm/wiki/迁移业界优秀模块到-spmjs.io-并反推的简易教程) diff --git a/zh-cn/develop-package/package-type.md b/zh-cn/develop-package/package-type.md new file mode 100644 index 0000000..3ca1df2 --- /dev/null +++ b/zh-cn/develop-package/package-type.md @@ -0,0 +1,3 @@ +# 组件类型 + + diff --git a/zh-cn/develop-project/README.md b/zh-cn/develop-project/README.md new file mode 100644 index 0000000..2540471 --- /dev/null +++ b/zh-cn/develop-project/README.md @@ -0,0 +1,136 @@ +# 项目开发 + +> 由于目前 spm 更侧重于解决组件方面的问题，项目开发的工具（比如 [spm-server](https://github.com/spmjs/spm-server) 、部署、项目的脚手架等) 并没有内置到 spm 中，需额外安装。 + +## 演示 + +![](http://gtms04.alicdn.com/tps/i4/TB1iN.pGXXXXXa3XpXXDs3XUXXX-699-360.gif) + +## 基本流程 + +1. 建 package.json +2. 开发和用 `spm install` 安装依赖 +3. 用 `spm-server` 调试 +4. 部署和发布 + +## 目录结构 + +``` +helloworld + ├─ dist/ (构建生成的目录，用于发布和部署) + ├─ spm_modules/ (依赖组件安装后所在目录) + ├─ index.js + ├─ index.css + ├─ index.html + ├─ package.json (配置文件，详见 package.json/README.html) +``` + +## 开发 + +编辑 `package.json`： + +```javascript +{ + "name": "helloworld", + "version": "0.1.0", + "spm": { + "output": [ + "index.js", + "index.css" + ], + "buildArgs": "--include standalone" + } +} +``` + +> output 用于声明哪些文件需要构建，buildArgs 用于配置构建选项，详见 [package.json](../package.json/README.md) 。 + +编辑 `index.js`： + +```javascript +var $ = require('jquery'); +$('body').append('
Hello World!
'); +``` + +编辑 `index.css`： + +```css +@import 'http://github.com/normalize.css'; +div { + color: red; +} +``` + +编辑 `index.html`： + +```html + + +``` + +## 安装依赖 + +在项目目录中执行命令： + +```bash +$ spm install jquery normalize.css --save +``` + +spm install 命令会从 `源：spmjs.io` 上下载依赖的组件，并保存到 `spm_modules` 下，结构如下： + +``` +spm_modules + ├─ jquery/2.1.1/ + ├─ normalize.css/3.0.1/ +``` + +## 本地调试 + +`spm-server` 是 spm 的本地调试工具之一，封装了不少常用的调试功能。比如 `livereload`, `https`，`less` 和 `coffee` ，详见 [spm-server 文档](spm-server.md) 。 + +```bash +$ npm install spm-server -g +$ spm-server + server: listen on 8000 +``` + +启动成功后，在浏览器里打开 http://localhost:8000 即可看到效果。 + +> 通过 `spm-server --livereload` 可开启 livereload 模式 (监听文件改动并自动刷新) + +## 构建 + +在项目目录中执行命令： + +```bash +$ spm build +``` + +该命令会分析 package.json，对 output 中指定的文件进行 CMD 转换、压缩等处理，然后输出到 `dist` 目录。 + +构建后 `dist` 的目录结构如下： + +```bash +dist + ├─ helloworld/0.1.0/ + ├─ index-debug.css + ├─ index-debug.js + ├─ index.css + ├─ index.js +``` + +> `dist` 目录路径中会包含版本号，通过版本化的非覆盖式发布可解决静态资源缓存更新、灰度发布、快速回滚、保留历史版本等问题。 + +## 部署和发布 + +`dist` 下的文件是用于发布的，把里面的文件传到服务器上即可。 + +> 如果需要 zip 包，可执行 `spm build --zip` 命令，在构建之后自动压缩 dist 目录。 + +## Congratulation + +至此，你应该已学会如何用 spm 构建一个简单的项目了吧。继续阅读： + +* [应用 bootstrap](develop-project/using-bootstrap.md) +* [spm-server 使用文档](develop-project/spm-server.md) + diff --git a/zh-cn/develop-project/modes.md b/zh-cn/develop-project/modes.md new file mode 100644 index 0000000..a7e65de --- /dev/null +++ b/zh-cn/develop-project/modes.md @@ -0,0 +1,38 @@ +# 不同的应用类型 + +## 应用分类 + +这里把应用简单地分成单页和多页两类。 + +### 单页应用 + +相对简单，理论上只需要引入一个 css 和一个 js 即可。比如 TODO 应用、淘宝首页、支付宝首页、Chrome 插件等，都属此类。 + +### 多页应用 + +包含多个页面，并且出于维护性或性能(缓存)上的考虑，在所有页面公共引入一个或多个文件。比如支付宝的收银台(选择、确认、结果)，淘宝的购物流程(购物车、确认订单、结果)，以及大部分网站(首页、列表、详情)，都属此类。 + + +## SPM 的构建策略 + +首先要熟悉 SPM 构建的两个参数：include 和 ignore ，通过这两个参数的组合，理论上可适应各种应用模式。 + +### include + +打包策略，可选 relative、all、standalone，分别表示打包相对依赖、打包所有依赖、打包所有依赖并可自运行，默认为 relative。 + +注意：standalone 会忽略 ignore 参数。 + +### ignore + +指定不进行 transport 的依赖，这些依赖： + +1. id 不会被 transport +1. 文件不会被打包进来 + +和 seajs.alias 配合使用，可解决多页面公用组件的问题。 + +## 总结 + +1. 单页应用 `--include standalone` +1. 多页应用 `--include all` + `--ignore` + `seajs.alias` diff --git a/zh-cn/develop-project/spm-server.md b/zh-cn/develop-project/spm-server.md new file mode 100644 index 0000000..8e42c95 --- /dev/null +++ b/zh-cn/develop-project/spm-server.md @@ -0,0 +1,99 @@ + +# spm-server ([source](https://github.com/spmjs/spm-server)) + +> 如果不喜欢本地启 server 的调试方法，可以试下 [seajs-wrap](https://github.com/seajs/seajs-wrap) 。 + +基于 [serve-spm](https://github.com/spmjs/serve-spm) 的 SPM3 本地调试工具，同时也内置了一些路径映射，可以很方便地进行线上调试。 + +## DEMO + +在`我的支付宝`页面调试 `arale-tip` 组件： + +![](https://t.alipayobjects.com/images/T10QJcXodWXXXXXXXX.gif) + +## 安装 + +```bash +$ npm install spm-server -g +``` + +## 特性 + +- 支持 `??` 协议的 `combo` 解析和代理 + + 比如请求 `/??a.js,b.js`，本地只有 `a.js`，没有 `b.js`，则会从 CDN 上获取 `b.js`，和 `a.js` 合并后输出。 + +- 支持 `livereload` + + 通过添加参数 `--livereload` 开启，需和 [Livereload Chrome 插件](https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei) 配合使用。 + +- 支持 `https` + + 通过添加参数 `--https` 开启。线上 assets 服务器是 https 协议，且需要调试线上问题时使用。 + +- 支持 `less` 和 `coffeescript` + + 比如，请求 `/a.css` 时会检查 `/a.less` 是否存在，然后实时编译返回。 + +## 用法 + +```bash +$ spm-server [OPTIONS] +``` + +## 选项 + +- `-p, --port `, 端口号, 默认为：`8000` +- `-b, --base `, base path to access package in production +- `--idleading `, 模块名前缀, 默认为：`{{name}}/{{version}}` +- `--https`, 同时开启 https proxy +- `--livereload`, 开启 livereload，需和 [livereload Chrome 插件](https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei) 配合使用 + +## 使用场景 + +- relative/all + - [内链引入 seajs，通过 seajs.use 载入所有模块](https://github.com/spmjs/spm-server/blob/master/test/fixtures/normal/normal.html) + - [内链 combo 引入 seajs 和依赖模块，通过 seajs.use 载入入口模块](https://github.com/spmjs/spm-server/blob/master/test/fixtures/normal/combo_deps.html) + - [内链 combo 引入 seajs 和所有模块，通过 seajs.use 初始化入口模块](https://github.com/spmjs/spm-server/blob/master/test/fixtures/normal/combo_all.html) +- standalone + - [单独引入入口模块](https://github.com/spmjs/spm-server/blob/master/test/fixtures/standalone/normal.html) + - [combo 引入入口模块和其他 JS 文件](https://github.com/spmjs/spm-server/blob/master/test/fixtures/standalone/combo.html) + - [base 不是根目录](https://github.com/spmjs/spm-server/blob/master/test/fixtures/standalone/taobao.html)，运行 `spm-server` 时指定 `base` + +## 路径规则 + +详见：[spmjs/serve-spm#2](https://github.com/spmjs/serve-spm/pull/2) + +``` +# 目录结尾，自动查找 index.htm 和 index.html +- /$ -> index.htm, index.html + +# 当前 pkg 的 dist 目录下的文件，代理到源码 +- ^/dist/curr_name/curr_version/a.js -> /a.js + +# 依赖模块的请求，先找 dist 下的(基于性能上的考虑)，再照 spm_modules 下的 +- ^/name/version/a.js -> /dist/name/version/a.js +- ^/name/version/a.js -> /spm_modules/name/version/a.js + +# handlebars 处理 +- ^handlebars-runtime.js, ^/dist/cjs/handlebars.runtime.js -> hanelebars.runtime.js + +# js require css 和 tpl 文件的处理 +- a.css.js^ -> a.css, a.tpl.js -> a.tpl, ... + +# 预编译语言，目前支持 less 和 coffeescript +- a.js^ -> a.coffee +- a.css^ -> a.less +``` + + +## FAQ + +* 部分文件我不想加 cmd wrap 怎么办? + + url 添加 `nowrap` 参数，比如 `/a.js?nowrap`。 + +* 和 `spm doc watch` 有什么区别? + + `doc watch` 面向组件开发。基于 nico，所以支持 markdown 解析，启动时会先生成 _site 目录，然后基于 _site 目录启动服务器。`spm-server` 面向应用开发。不生成额外的目录，支持一些常用的应用开发功能，比如 `livereload`, `https server`, `cdn combo proxy` 等。 + diff --git a/zh-cn/develop-project/strategy.md b/zh-cn/develop-project/strategy.md new file mode 100644 index 0000000..95a833c --- /dev/null +++ b/zh-cn/develop-project/strategy.md @@ -0,0 +1,46 @@ + +# 应对不同的项目类型 + +由于业务类型的不同，以及前端技术的发展，我们现在要面对各种项目的类型。有些是单页应用，有些是多页应用，多页应用可能还要考虑页面之间的缓存共用，等等。 + +而针对这些问题，SPM 提供了 `include` 和 `ignore` 这两个构建参数(详见：[buildArgs](../package.json/buildArgs.md) )。通过他们的组合，理论上可以满足各种项目类型的需要。 + +## 单页应用和不太在意性能的多页应用 + +推荐用 `--include standalone`，这种方式会把所有的依赖都打包到一起，并且可以自运行且无需 loader 。 + +HTML 里的使用方法： + +```html + +``` + +## 在意性能的多页应用 + +上面这种方式处理多页应用时会有一定量的冗余。 + +比如有两个页面，每个页面都依赖 jQuery，用上面的方式会把 jQuery 打包到各自的输出文件里，这样 jQuery 就不能在两个页面间公用缓存了。 + +这时推荐用 `--include all --ignore jquery`，构建时会打包除 jquery 外的所有依赖为 CMD 模块，通过 seajs 载入运行。ignore 的 jquery 可以通过 seajs 的 alias 配置指定具体的版本。 + +HTML 里的使用方法： + +```html + + +``` + +## 其他 + +- 还可以选择 `--include relative` 的方式，构建时只会包含相对目录的本地文件，不会包含依赖。所以所有的依赖组件都需要被发布到 cdn 上。 + +## 延伸阅读 + +- [standalone 支持 umd 方案整理](https://github.com/spmjs/spm/issues/892) diff --git a/zh-cn/develop-project/using-bootstrap.md b/zh-cn/develop-project/using-bootstrap.md new file mode 100644 index 0000000..2151c9f --- /dev/null +++ b/zh-cn/develop-project/using-bootstrap.md @@ -0,0 +1,6 @@ +# 应用 BootStrap + +## 演示 + +![](https://t.alipayobjects.com/images/T1FkpcXXNSXXXXXXXX.gif) + diff --git a/zh-cn/environment.md b/zh-cn/environment.md new file mode 100644 index 0000000..85e3bea --- /dev/null +++ b/zh-cn/environment.md @@ -0,0 +1,61 @@ +# 环境配置 + +## 环境准备 + +### 安装 node + +作为一个前端，你需要 node 环境。 + +推荐使用 [nvm](https://github.com/creationix/nvm) 来安装： + +```bash +$ curl https://raw.githubusercontent.com/creationix/nvm/v0.16.1/install.sh | bash +$ nvm install 0.10.24 +$ nvm alias default 0.10.24 +``` + +另外，也可以在[官方下载](http://nodejs.org/download/)或[通过包管理工具安装](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager)。 + +### 去除 sudo + +**如果你是用 nvm 来安装的 node，请跳过步骤。** + +使用 npm 安装模块的时候经常要输入 sudo，还要输入密码，这点很让人烦躁。下面你可以简单粗暴的去除 sudo（看看作者的[软文](http://howtonode.org/introduction-to-npm)） + +``` bash +$ sudo chown -R $USER /usr/local +``` + +### 安装 git + +版本管理工具也是必须的，可以先[了解 git 的相关内容](http://rogerdudler.github.com/git-guide/index.zh.html) 。 + +git 下载地址如下 + + - [git for mac](https://code.google.com/p/git-osx-installer/downloads/list?can=3&q=&sort=-uploaded&colspec=Filename+Summary+Uploaded+Size+DownloadCount) + - [git for windows ](https://code.google.com/p/msysgit/downloads/list?q=full+installer+official+git) + +### 安装 spm + +```bash +$ npm install spm -g +``` + +## windows 环境 + +推荐使用 windows 的包管理工具 [chocolatey](https://github.com/chocolatey/chocolatey)。 + +安装 nodejs 和 git ： + +``` +c:\> cinst git.install +c:\> cinst nodejs.install +``` + +设置环境变量： + +``` +PATH = C:\Users\{{username}}\AppData\Roaming\npm +NODE_PATH = C:\Users\{{username}}\AppData\Roaming\npm\node_modules +``` + diff --git a/zh-cn/get-started.md b/zh-cn/get-started.md new file mode 100644 index 0000000..9cab75e --- /dev/null +++ b/zh-cn/get-started.md @@ -0,0 +1,66 @@ + +# 新手入门 + +## 介绍 + +[spm](https://github.com/spmjs/spm) 是一套完整的浏览器端组件管理解决方案，包含对于 JavaScript、CSS 和模板的处理。 + +![SPM LOGO](https://i.alipayobjects.com/i/localhost/png/201404/2YQxOTYoFp.png) + +所有 `源：spmjs.io` 上的组件都是以 CommonJS 的方式组织，并可以通过 [seajs](http://seajs.org/) 加载运行。同时，我们基于 [spm](https://github.com/spmjs/spm) 提供了一套完整的组件生命周期管理方案，包含以下特性： + +- 初始化 +- 依赖安装 +- 本地开发 +- 发布到 [spmjs.io](http://spmjs.io/) +- 单元测试 +- 文档服务 +- 构建 + +[spmjs.io](http://spmjs.io/) 是针对 spm 的组件管理服务。你可以在这里搜索需要的组件，也可以发布组件到这里。如果需要，你还可以搭建自己的私有源服务或镜像。 + +## 安装 + +```bash +$ npm install spm -g +``` + +> 如果遇到安装问题，请先确认 [环境配置](environment.html) 是否正确，以及搜索下 [别人踩过的安装坑](https://github.com/spmjs/spm/search?q=install&type=Issues&utf8=%E2%9C%93)。 + +## 使用 + +> 以下是组件开发的使用入门，你也可以直接跳到[项目开发](develop-project/README.html)。 + +初始化组件： + +```bash +$ mkdir example +$ cd example +$ spm init +``` + +安装依赖： + +```bash +$ spm install jquery --save +$ spm install moment@2.6.0 --save +``` + +发布到 [spmjs.io](http://spmjs.io/) + +```bash +$ spm publish +``` + +> 你可能需要先执行 `spm login` 来获取权限，登录 [spmjs.io](http://spmjs.io) 之后在 http://spmjs.io/account 可以找到 `authkey`。 + +如果组件包的尺寸过大，可以添加 `.spmignore` 来过滤掉不需要的文件，格式同 [.gitignore](http://git-scm.com/docs/gitignore)。 + +## 贡献 + +欢迎通过以下方式来贡献 spm ： + +- [Bug reports](https://github.com/spmjs/spm/issues) +- [Feature requests](https://github.com/spmjs/spm/issues) +- [Pull requests](https://github.com/spmjs/spm/pulls) +- 推广 spm 到你的朋友圈 diff --git a/zh-cn/package.json/README.md b/zh-cn/package.json/README.md new file mode 100644 index 0000000..cb5d938 --- /dev/null +++ b/zh-cn/package.json/README.md @@ -0,0 +1,77 @@ +# Package.json + +`spm` 使用和 `npm` 基本一致的 `package.json` 来描述组件。除了包含一些特殊配置的 `spm` 域之外，其他都和 `npm` 保持一致。 + +### Fields + +Field | Description | +------------ | ------------- | +name* | 组件名，全部小写，以 `-` 或 `.` 分隔单词 +version* | 语义化的版本号，比如 1.0.0 +description | a brief description of your package +keywords | an array contains keywords +homepage | url of your package's website +author | author of this package: `Hsiaoming Yang ` or `{ "name": "Hsiaoming Yang", "email": "me@lepture.com" }` +maintainers | an array of maintainers, just like author +repository | Specify the place where your code lives. `{ "type": "git", "url": "http://github.com/isaacs/npm.git" }` +bugs | The url to your project's issue tracker and / or the email address to which issues should be reported. +license | license +**spm*** | +spm.main | 组件的唯一入口，默认为 `index.js`，如果是一个 css 组件，可以设置为 `index.css` +spm.output | 指定构建输出的文件，以数组表示，支持 glob 格式：`src/**/*.js` +spm.dependencies | 指定依赖组件 +spm.devDependencies | 指定开发状态下的依赖组件 +spm.tests | 指定测试文件，支持 glob 格式：`tests/*-spec.js` +spm.buildArgs | 配置 `spm build` 的命令行参数 +spm.registry | 指定组件发布的目标源，默认为 `http://spmjs.io` +spm.ignore | 发布到源上时需要忽略的文件，以数组表示，功能同 `.spmignore` + +### 一个简单的例子 + +```json +{ + "name": "arale-calendar", + "version": "1.1.0", + "description": "Calendar widget.", + "keywords": [ + "widget", + "month", + "datepicker" + ], + "author": "Hsiaoming Yang ", + "maintainers": [ + "hotoo ", + "shengyan " + ], + "homepage": "http://aralejs.org/calendar/", + "repository": { + "type": "git", + "url": "https://github.com/aralejs/calendar.git" + }, + "bugs": { + "url": "https://github.com/aralejs/calendar/issues" + }, + "license": "MIT", + "spm": { + "main": "calendar.js", + "dependencies": { + "jquery": "1.7.2", + "moment": "2.6.0", + "arale-base": "1.1.0", + "arale-position": "1.1.0", + "arale-iframe-shim": "1.1.0", + "handlebars": "1.3.0", + "arale-widget": "1.2.0" + }, + "devDependencies": { + "expect.js": "0.3.1" + }, + "tests": "tests/*-spec.js", + "ignore": [ + "dist", + "_site" + ], + "buildArgs": "--ignore jquery" + } +} +``` diff --git a/zh-cn/package.json/buildArgs.md b/zh-cn/package.json/buildArgs.md new file mode 100644 index 0000000..ce49dd2 --- /dev/null +++ b/zh-cn/package.json/buildArgs.md @@ -0,0 +1,87 @@ +# buildArgs + +## 参数列表 + +Field | Description | +----- | ----------- | +dest | 输出目录，默认为 `dist` +include | 指定打包策略，可选 relative、all、standalone、umd，默认为 `relative` +ignore | 指定不进行 transport 的依赖 +skip | 指定不进行分析的依赖 +idleading | 模块名前缀，默认为 `{{name}}/{{version}}` +withDeps | 同时打包所有依赖，默认为 `false` + +## include + +Field | Description | +----- | ----------- | +relative | 打包相对依赖 +all | 打包所有依赖 +standalone | 打包所有依赖并可自运行 +umd | 在 standalone 基础上再添加 `umd wrap` + +### 举例说明 + +比如有一个组件 `a/0.1.0/index.js`： + +```javascript +require('./relative'); +require('b'); +``` + +include 为 `relative` 时，打包出来是： + +```javascript +define('a/0.1.0/index.js', ['a/0.1.0/relative', 'b/0.1.0/index.js'], function() {}); +define('a/0.1.0/relative.js', function() {}); +``` + +include 为 `all` 时，打包出来是： + +```javascript +define('a/0.1.0/index.js', ['a/0.1.0/relative', 'b/0.1.0/index.js'], function() {}); +define('a/0.1.0/relative.js', function() {}); +define('b/0.1.0/index.js', function() {}); +``` + +include 为 `standalone` 时，打包出来是： + +```javascript +(function(){ +var a_0_1_0_index_js, a_0_1_0_relative_js, b_0_1_0_index_js; +b_0_1_0_index_js = (function() {})(); +a_0_1_0_relative_js = (function() {})(); +a_0_1_0_index_js = (function() {})(); +})(); +``` + +include 为 `umd` 时，打包出来是： + +```javascript +(function(){ +var a_010_index_js, a_010_relative_js, b_010_index_js; +b_010_index_js = (function() {})(); +a_010_relative_js = (function() {})(); +a_010_index_js = (function() {})(); + +// umd wrap +if (typeof exports == "object") { + module.exports = a_010_index_js; +} else if (typeof define == "function" && define.amd) { + define([], function(){ return a_010_index_js }); +} else { + this["a"] = a_100_indexjs; +} +})(); +``` + +## ignore + +还是上面的例子，如果 include 为 `relative` 并且 ignore 为 `b`，打包出来是： + +```javascript +define('a/0.1.0/index.js', ['a/0.1.0/relative', 'b'], function() {}); +define('a/0.1.0/relative.js', function() {}); +``` + + diff --git a/zh-cn/registry/README.md b/zh-cn/registry/README.md new file mode 100644 index 0000000..e9f152f --- /dev/null +++ b/zh-cn/registry/README.md @@ -0,0 +1,31 @@ +# 源 + +## 什么是源? + +这里的源指的是 spm 的服务端，即：http://spmjs.io 。所有源上的包都是以 commonjs 或 umd 的形式存在。 + +## SPM 为什么选择自搭源? + +这里有具体的讨论和分析：https://github.com/spmjs/spm/issues/718 + +另外，个人觉得自搭源最重要的优势是`稳定性`，尤其是对于大公司来说。很难想象研发流程的链路上需要依赖一个外部的不稳定服务，比如随时可能被墙的 github，有速度问题的 npm 。 + +出于这个考虑，SPM 的源提供了`同步机制`，自己搭建的私有源可以从 spmjs.io 上定时同步。比如在支付宝，就有搭建自己的私有源，从而保证研发流程的稳定。 + +## 组件池构成 + +![](https://t.alipayobjects.com/images/T1rANcXhlAXXXXXXXX.png) + +如上图。目前源上的组件池主要包含以下 3 部分： + +- 业界优秀开源模块 (持续推广和迁移中，详见：[awesome-javascript](https://github.com/sorrycc/awesome-javascript)) +- 个人发布模块 +- 团队和公司的产品 (通常带前缀，比如 arale-dialog) + +欢迎共建组件池。 + +附：https://github.com/spmjs/spm/wiki/迁移业界优秀模块到-spmjs.io-并反推的简易教程 + + + + diff --git a/zh-cn/registry/private.md b/zh-cn/registry/private.md new file mode 100644 index 0000000..ec060cb --- /dev/null +++ b/zh-cn/registry/private.md @@ -0,0 +1,31 @@ + +# 私有源 + +自搭私有源通常有两个目的： + +- 保障研发流程的稳定性 +- 保证业务组件的私有性 + +## 单向同步 + +![](https://t.alipayobjects.com/images/T1r7BcXglTXXXXXXXX.png) + +私有源可开启来自公有源 (spmjs.io) 的单向同步。 + +## 搭建 + +详见：https://github.com/spmjs/spmjs.io 。然后可以修改 `config/base.yaml` 里的 `sync` 为 `on` 可开启来自 spmjs.io 的单向同步。 + +## 使用 + +spm 里所有和源操作相关的命令，都可以添加 `--registry` 参数来指定源路径，比如： + +```bash +$ spm publish --registry http://path/to/your-private-registry +``` + +另外，如果不想每次都多输入 `--registry` 参数，也可以把配置到 spmrc 里： + +```bash +$ spm config registry http://path/to/your-private-registry +```