npm

@wulechuan/project-skeleton-for-libs

简介

安装本工具，以期在每次运行本工具时自动构建一个项目文件框架。

其幕后具体动作是，将名为“the-skeleton-to-distribute”文件夹内的所有文件、文件夹深度复制到制定的文件夹中。

所发布之内容包含：

1. source文件夹，内含一个空的JavaScript类，并有JSDOC风格的描述文字，借助已经设计好的gulp任务，可自动产生README.MD。

2. build文件夹，用于存放source文件夹的输出内容。

3. examples文件夹，内含一套空的范例：一个HTML和一个JavaScript。

4. docs文件夹，内含一个空的API.md。

5. test文件夹，内含一个极为基础的mocha测试用例组。

6. .vscode文件夹，内含微软Visual Studio Code的配置。

7. ESLint配置文件两个（.eslintrc.js与.eslintignore）。

8. .gitignore文件。

9. webpack.config.js，用于编译各个examples文件夹内的各个范例。

10. gulpfile.js，用于自动编译source文件夹内的源文件，至build文件夹；同时亦会调用webpack，编译所有范例。

11. 一个空的README.md。根据现有gulpfile的配置，该README系由source文件夹内的源代码中的注释自动生成的。因此：

    如果不更改gulpfile，请勿手工编辑该README文件！

    如果不更改gulpfile，请勿手工编辑该README文件！

    如果不更改gulpfile，请勿手工编辑该README文件！

12. 一些预定义的npm脚本命令。您可在命令行工具中键入：

    npm run

    来查阅可用脚本之列表。

安装

目前，以全局命令行形式运行该构建工具尚未实现，因此，利用npm或yarn来安装本工具没有意义。

暂时，仅能利用“git克隆”命令达到目的。做法如下：

$cd <somewhere-you-d-like-to-save-this-tool>
$git clone https://github.com/wulechuan/javascript-wulechuan-project-skeleton-for-libs.git

然后安装所有其依赖之模块。做法如下：

$npm install

须注意本工具另外还依赖gulp-cli

由于本工具依赖一个名为“gulp”的工具，且须从命令行运行ggulp因此你亦须另行确保gulp的命令行模块（即gulp-cli）也已安装于你的计算机中。而gulp-cli常常被全局安装于计算机上，因此，上述单纯的（不附加任何参数的）“npm install”命令不会安装之。如果你尚未安装gulp-cli，你须另行安装之，如下（其中“-g”参数代表全局安装）：

$npm i -g gulp-cli

简而言之，gulp工具分主体和命令行模块两部分。 尽管我们常常（但不是必须）为我们的每个项目分别独立安装gulp的主体， 但gulp的命令行模块（即gulp-cli）常常建议全局安装之，而不必为每个项目分别安装。 凡全局安装之npm模块，单纯的（不附加任何参数的）“npm install”命令均无法触及。

参阅【Gulp官方网站】。

使用方法

首先，打开命令行工具，进入本工具的安装文件夹：

$cd <somewhere-you-d-like-to-save-this-tool>/javascript-wulechuan-project-skeleton-for-libs

然后，依以下任何一种方法运行本工具：

1.  $npm run copy

2.  $npm run copy "\<your-target-folder-that-need-not-exist-beforehand\>"

3.  $gulp

4.  $gulp --to "\<your-target-folder-that-need-not-exist-beforehand\>"

注意：

由于我在“gulpfile.js”文件中做了如下配置：

  const defaultDistributionFolder = '../a-new-project';

故而默认的复制目标文件夹为“<当前文件夹>/../a-new-project”。上述方法1、3省略了输出文件夹，因此，这两种方法的输出文件夹即为:

  "\<somewhere-you-d-like-to-save-this-tool\>/a-new-project"

善后工作

package.json

在npm的配置文件（即“package.json”）中，有一些默认值是临时的，必须及时填写真实值。

目前，须修订的配置项有：

配置项 | 临时值 ------|------- name | "__untitled-project__" author | "吴乐川" main | "build/__the-source-file-of-the-lib__.min.js"

gulpfile.js

在修订package.json之后，可以安全地把“gulpfile.js”中的名为“TEMP: TIP”临时任务删除。同时，“default”对上述临时任务的依赖也须一并去除。

主源文件

主源文件的临时名称为“__the-source-file-of-the-lib__.js”。其中包含一个临时的“alert”语句，用于提醒你及时做修订工作。因此，在你完成之前的各项修订后，这个alert语句也应去除。

注意：

如果不去除上述alert语句，则mocha测试框架可能无法正常运行。

Introduction

Each time you run this tool, a new folder might be created, containing a skeleton, or a scaffold, if you prefer, of a new project. The folder structure and configurations of the said project are optimized orienting the development of a javascript library.

Behinde the scene, this tool simply copy everything under the sub-folder named "the-skeleton-to-distribute" of this package to a specific distribution folder, or a default folder if omitted. The said default folder is "../a-new-project".

The distributed project skeleton includes:

1. The "source" folder, which contains an empty javascript class definition. The jsdoc style comments above the definition contains an empty README, which will be used to automatically generate the README.MD file, via a pre-configured gulp task.

2. The "build" folder, which contains the compiled version of those files in the "source" folder.

3. The "examples" folder, which contains an skeleton of an example, an HTML file and a JavaScript file.

4. The "docs" folder, which contains an empty API.md.

5. The "test" folder, which contains an very basic testing case group utilizing the "mocha" framework and the "should" assertion lib.

6. The ".vscode", which contains the configuration for the Microsoft Visual Studio Code.

7. Two configuration files for ESLint.

8. The ".gitignore" file.

9. The "webpack.config.js", used to compile all examples under the "examples" folder.

10. The "gulpfile.js", which is used to compile the source files of the lib and output the compiled version into the build folder. Also, the gulp will invoke the webpack, to compile all examples.

11. An empty README.md. According to the existing gulpfile configuration, this README.md will be generated automatically though what's in the source code comments. So:

    Unless gulpfile is modified, please avoid editing the README.md!

    Unless gulpfile is modified, please avoid editing the README.md!

    Unless gulpfile is modified, please avoid editing the README.md!

12. Some pre-defined npm scripts. You can simply open up a terminal window and type:

    npm run

    to checkout what's available.

Installation

At present, the cli(command-line interface) formation is NOT supported. Thus it's meaningless to install this tool via npm or yarn.

Simply take the "git clone" approach, as shown below:

$git clone https://github.com/wulechuan/javascript-wulechuan-project-skeleton-for-libs.git

Then, install all denpendencies of this tool, like so:

$npm install

Also notice that this tool depends on gulp-cli as well

This tool depends on a famous tool, named "gulp". While the core funcationalities are splitted into two parts, the gulp bin and the gulp-cli.

Since in most cases the "gulp-cli" is suggested to install globally, the command "npm install", as it takes no arguments at all, will not cover the installation of the "gulp-cli", althought it does cover the installation of the so-called "gulp bin".

So if you haven't installed the gulp-cli yet, please also do this:

$npm i -g gulp-cli

See Gulp Official Site.

Usage

First, let's goto the folder of this tool, as that we can run it.

$cd <somewhere-you-d-like-to-save-this-tool>/javascript-wulechuan-project-skeleton-for-libs

The, pick any approach listed below:

1.  $npm run copy

2.  $npm run copy "\<your-target-folder-that-need-not-exist-beforehand\>"

3.  $gulp

4.  $gulp --to "\<your-target-folder-that-need-not-exist-beforehand\>"

Note:

Since I have made a configuration in the "gulpfile.js" like so:

  const defaultDistributionFolder = '../a-new-project';

the default output folder will be "../a-new-project". Among the approaches listed above, both 1) and 3) omit the output folder argument, thus the output folder will be:

  "\<somewhere-you-d-like-to-save-this-tool\>/a-new-project"

Post-installation Tasks

package.json

Some configuration items amony the package.json are holding temporary values. You MUST fill real, meaningful values to replace the existing ones.

These items are:

Item | Temporary Value ------|------- name | "__untitled-project__" author | "吴乐川" main | "build/__the-source-file-of-the-lib__.min.js"

gulpfile.js

After modification of the package.json, you can safely remove the task named "TEMP: TIP" inside the "gulpfile.js". You should also remove those denpendencies of the "default" task accordingly.

The Chief Source Code JavaScript File

The chief source code js file is temporarily named "__the-source-file-of-the-lib__.js". There is an "alert" statement at the very top of the file content. This alert is for prompting you to do those modifications mentioned in above sections. So after all those are done, this alert should also be removed.

Note

If the alert statement is NOT removed, the mocha unit testing framework might NOT work.