diff --git a/.npmignore b/.npmignore new file mode 100644 index 0000000..be02fa0 --- /dev/null +++ b/.npmignore @@ -0,0 +1,8 @@ +node_modules/ +dist/ +.git/ +.gitignore +*.log +.DS_Store +.vscode/ +.idea/ diff --git a/PUBLISH.md b/PUBLISH.md new file mode 100644 index 0000000..bf36b81 --- /dev/null +++ b/PUBLISH.md @@ -0,0 +1,59 @@ +# 发布到npm指南 + +## 发布步骤 + +1. **确保你有npm账号** + ```bash + npm login + ``` + +2. **检查包名是否可用** + ```bash + npm view create-userscript + ``` + 如果显示404错误，说明包名可用。 + +3. **发布到npm** + ```bash + npm publish + ``` + +4. **验证发布成功** + ```bash + npm view create-userscript + ``` + +## 使用方式 + +发布成功后，用户可以通过以下方式使用： + +```bash +# 方式1：使用npm create +npm create @javascript-reverse-engineering-infrastructure/userscript my-project + +# 方式2：使用npx +npx @javascript-reverse-engineering-infrastructure/create-userscript my-project +``` + +## 更新版本 + +当需要更新模板时： + +1. 修改代码 +2. 更新版本号： + ```bash + npm version patch # 补丁版本 (0.0.1 -> 0.0.2) + npm version minor # 次版本 (0.0.1 -> 0.1.0) + npm version major # 主版本 (0.0.1 -> 1.0.0) + ``` +3. 重新发布： + ```bash + npm publish + ``` + +## 注意事项 + +- 包名 `create-userscript` 需要在npm上是唯一的 +- 如果包名已被占用，需要修改 `package.json` 中的 `name` 字段 +- 建议使用语义化版本号 +- 发布前确保所有文件都在 `files` 字段中正确配置 diff --git a/README.md b/README.md index 8437d12..7968f48 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,30 @@ # 三、快速开始 -在当前仓库（https://github.com/JSREI/userscript-template）选择“`Use this template`” --> “`Create a new repository`”，从这个模板仓库创建一个新的仓库： +## 方式一：使用npm命令创建（推荐） + +使用npm命令直接创建新项目： + +```bash +npm create @javascript-reverse-engineering-infrastructure/userscript my-userscript +``` + +或者使用npx： + +```bash +npx @javascript-reverse-engineering-infrastructure/create-userscript my-userscript +``` + +然后进入项目目录并安装依赖： + +```bash +cd my-userscript +npm install +``` + +## 方式二：从GitHub模板创建 + +在当前仓库（https://github.com/JSREI/userscript-template）选择“`Use this template`” --> “`Create a new repository`”，从这个模板仓库创建一个新的仓库： ![image-20230816233501101](README.assets/image-20230816233501101.png) @@ -95,6 +118,42 @@ npm install ![image-20230817004653299](README.assets/image-20230817004653299.png) +## Banner支持 + +项目支持在编译后的代码中添加自定义banner。在项目根目录的`banner.txt`文件中，你可以添加ASCII艺术字或其他装饰性文本： + +``` +▗▄▄▄▖▗▖ ▗▖▗▄▄▖ ▗▄▄▄▖ ▗▄▄▖ ▗▄▄▖▗▄▄▖ ▗▄▄▄▖▗▄▄▖▗▄▄▄▖ + █ ▝▚▞▘ ▐▌ ▐▌▐▌ ▐▌ ▐▌ ▐▌ ▐▌ █ ▐▌ ▐▌ █ + █ ▐▌ ▐▛▀▘ ▐▛▀▀▘ ▝▀▚▖▐▌ ▐▛▀▚▖ █ ▐▛▀▘ █ + █ ▐▌ ▐▌ ▐▙▄▄▖▗▄▄▞▘▝▚▄▄▖▐▌ ▐▌▗▄█▄▖▐▌ █ +``` + +编译时，banner内容会被自动插入到油猴脚本头部注释中，支持以下变量替换： +- `${name}` - 项目名称 +- `${version}` - 版本号 +- `${description}` - 项目描述 +- `${author}` - 作者信息 +- `${repository}` - 仓库地址 +- `${namespace}` - 命名空间 +- `${document}` - 文档地址 + +编译后的效果： +```javascript +// ==UserScript== +// @name my-project +// @version 1.0.0 +// ... +// ==/UserScript== + +// ▗▄▄▄▖▗▖ ▗▖▗▄▄▖ ▗▄▄▄▖ ▗▄▄▖ ▗▄▄▖▗▄▄▖ ▗▄▄▄▖▗▄▄▖▗▄▄▄▖ +// █ ▝▚▞▘ ▐▌ ▐▌▐▌ ▐▌ ▐▌ ▐▌ ▐▌ █ ▐▌ ▐▌ █ +// █ ▐▌ ▐▛▀▘ ▐▛▀▀▘ ▝▀▚▖▐▌ ▐▛▀▚▖ █ ▐▛▀▘ █ +// █ ▐▌ ▐▌ ▐▙▄▄▖▗▄▄▞▘▝▚▄▄▖▐▌ ▐▌▗▄█▄▖▐▌ █ + +// 你的代码... +``` + 然后就可以开心的写代码了，在编写代码的时候你可以使用`npm`命令为项目添加依赖，对于一个稍微复杂点的脚本而言很可能会引用外部的依赖： ```bash diff --git a/README_en.md b/README_en.md index c9694ab..c776ebc 100644 --- a/README_en.md +++ b/README_en.md @@ -14,6 +14,29 @@ A plan for using `Node.js` + `Webpack` for modular development of Tampermonkey s # 3. Quick Start +## Method 1: Using npm command (Recommended) + +Create a new project directly using npm command: + +```bash +npm create @javascript-reverse-engineering-infrastructure/userscript my-userscript +``` + +Or using npx: + +```bash +npx @javascript-reverse-engineering-infrastructure/create-userscript my-userscript +``` + +Then enter the project directory and install dependencies: + +```bash +cd my-userscript +npm install +``` + +## Method 2: Create from GitHub template + To quickly get started with the project template, follow these steps: 1. Go to the repository at [https://github.com/JSREI/userscript-template](https://github.com/JSREI/userscript-template). @@ -108,6 +131,42 @@ In addition to variable substitution, all other content will be preserved as is, ![image-20230817004653299](README.assets/image-20230817004653299.png) +## Banner Support + +The project supports adding custom banners to the compiled code. In the `banner.txt` file in the project root directory, you can add ASCII art or other decorative text: + +``` +▗▄▄▄▖▗▖ ▗▖▗▄▄▖ ▗▄▄▄▖ ▗▄▄▖ ▗▄▄▖▗▄▄▖ ▗▄▄▄▖▗▄▄▖▗▄▄▄▖ + █ ▝▚▞▘ ▐▌ ▐▌▐▌ ▐▌ ▐▌ ▐▌ ▐▌ █ ▐▌ ▐▌ █ + █ ▐▌ ▐▛▀▘ ▐▛▀▀▘ ▝▀▚▖▐▌ ▐▛▀▚▖ █ ▐▛▀▘ █ + █ ▐▌ ▐▌ ▐▙▄▄▖▗▄▄▞▘▝▚▄▄▖▐▌ ▐▌▗▄█▄▖▐▌ █ +``` + +During compilation, the banner content will be automatically inserted into the userscript header comments, supporting the following variable substitutions: +- `${name}` - Project name +- `${version}` - Version number +- `${description}` - Project description +- `${author}` - Author information +- `${repository}` - Repository address +- `${namespace}` - Namespace +- `${document}` - Document address + +Compiled result: +```javascript +// ==UserScript== +// @name my-project +// @version 1.0.0 +// ... +// ==/UserScript== + +// ▗▄▄▄▖▗▖ ▗▖▗▄▄▖ ▗▄▄▄▖ ▗▄▄▖ ▗▄▄▖▗▄▄▖ ▗▄▄▄▖▗▄▄▖▗▄▄▄▖ +// █ ▝▚▞▘ ▐▌ ▐▌▐▌ ▐▌ ▐▌ ▐▌ ▐▌ █ ▐▌ ▐▌ █ +// █ ▐▌ ▐▛▀▘ ▐▛▀▀▘ ▝▀▚▖▐▌ ▐▛▀▚▖ █ ▐▛▀▘ █ +// █ ▐▌ ▐▌ ▐▙▄▄▖▗▄▄▞▘▝▚▄▄▖▐▌ ▐▌▗▄█▄▖▐▌ █ + +// Your code... +``` + Then you can happily start coding. While writing code, you can use the `npm` command to add dependencies to your project. For a slightly more complex script, it is very likely to reference external dependencies: ```bash diff --git a/package.json b/package.json index 70e3f52..f1853b8 100644 --- a/package.json +++ b/package.json @@ -1,11 +1,22 @@ { - "name": "userscript-foo", - "version": "0.0.1", - "description": "this is userscript's description", + "name": "@javascript-reverse-engineering-infrastructure/create-userscript", + "version": "1.0.0", + "description": "A template for developing userscripts with Node.js and Webpack", "main": "index.js", + "bin": { + "create-userscript-template": "./bin/create-userscript.js" + }, "repository": "https://github.com/JSREI/userscript-template.git", "namespace": "https://github.com/JSREI/userscript-template.git", "document": "https://github.com/JSREI/userscript-template.git", + "keywords": [ + "userscript", + "tampermonkey", + "greasemonkey", + "template", + "webpack", + "create" + ], "scripts": { "build": "webpack --config webpack.prod.js", "watch": "webpack --watch --config webpack.dev.js" @@ -16,5 +27,11 @@ "webpack": "^5.88.2", "webpack-cli": "^5.1.4", "webpack-merge": "^5.9.0" - } + }, + "files": [ + "bin/", + "template/", + "README.md", + "LICENSE" + ] } diff --git a/website/index.html b/website/index.html index 9836150..29a9355 100644 --- a/website/index.html +++ b/website/index.html @@ -3,7 +3,7 @@ - UserScript Template - 油猴脚本开发模板 + UserScript Template - 现代化油猴脚本开发模板 + + +

UserScript Template

-

使用 Node.js + Webpack 模块化开发油猴脚本的高效方案

+

现代化油猴脚本开发模板 - 支持模块化开发、热加载、npm包管理

-
@@ -976,18 +1233,32 @@

UserScript Template

核心特性

+
+
⚡
+
+

一键创建项目

+

通过 npm 命令一键创建项目，无需手动配置，开箱即用

+
+
📦

模块化开发

-

不再需要在单个 JavaScript 文件中组织代码，而是采用WebPack模块化管理代码，提升开发体验与效率

+

使用 Webpack 模块化管理代码，告别单文件开发的痛苦

🔄

热加载支持

-

开发时修改代码自动编译打包加载，让测试更高效

+

开发时修改代码自动编译，实时预览效果

+
+
+
+
🎨
+
+

Banner 支持

+

支持自定义 ASCII 艺术字，让你的脚本更有个性

@@ -997,11 +1268,11 @@

符合商店要求

打包后为高可读性的单文件，完全符合油猴商店上架政策

-
+
🚀

发布友好

-

打包后生成高可读性的单文件脚本，完全符合油猴商店的上架要求，无需额外处理

+

一键构建发布版本，无需额外处理即可上架

@@ -1018,32 +1289,65 @@

快速开始

  1. 创建项目

    -

    在 GitHub 模板仓库选择 "Use this template" 创建新仓库

    - - - - - - 前往模板仓库 - - - - - - Loading... - - - 创建项目示例 +
    + + +
    + +
    +

    推荐方式 - 使用 npm 命令一键创建项目：

    + 
    # 使用 npm create（推荐）
+npm create @javascript-reverse-engineering-infrastructure/userscript my-userscript
+
+# 或者使用 npx
+npx @javascript-reverse-engineering-infrastructure/create-userscript my-userscript
+
+# 进入项目目录
+cd my-userscript
+
+# 安装依赖
+npm install
    +
    + 优势： 自动配置所有必要文件，包括 webpack 配置、package.json、banner.txt 等，开箱即用！ +
    +
    + +
    +

    在 GitHub 模板仓库选择 "Use this template" 创建新仓库

    + + + + + + 前往模板仓库 + + + + + + Loading... + + + 创建项目示例 +
  2. -

    安装依赖

    - 
    git clone [你的仓库地址]
-cd [项目目录]
-npm install
    +

    开始开发

    +

    项目创建完成后，你就可以开始开发了！项目结构如下：

    + 
    my-userscript/
+├── src/                 # 源代码目录
+│   ├── index.js        # 入口文件
+│   ├── foo_module/     # 示例模块
+│   └── bar_module/     # 示例模块
+├── dist/               # 编译输出目录
+├── banner.txt          # Banner 文件
+├── userscript-headers.js # 油猴脚本头部配置
+├── webpack.*.js        # Webpack 配置
+└── package.json        # 项目配置
  3. -

    启动热编译

    -

    在项目目录下运行以下命令启动开发服务：

    +

    启动开发模式

    +

    在项目目录下运行以下命令启动开发服务，支持热重载：

    @@ -1137,6 +1441,57 @@

    构建发布

+ +

油猴本地调试指南

在开发过程中，您需要在油猴中创建一个指向本地文件的脚本。具体步骤如下：

@@ -1245,21 +1600,60 @@

开发调试