{"_id":"@alimir/wp-toolkit","_rev":"4-01d306ad9a94c7237aae667a863efe8c","name":"@alimir/wp-toolkit","dist-tags":{"latest":"2.0.1"},"versions":{"1.1.3":{"name":"@alimir/wp-toolkit","version":"1.1.3","keywords":["wordpress","wordpress-plugin","build","deploy","grunt","sass","wordpress-org","svn","rsync"],"author":{"url":"https://wpulike.com","name":"TechnoWich","email":"wpulike@gmail.com"},"license":"MIT","_id":"@alimir/wp-toolkit@1.1.3","maintainers":[{"name":"alimir","email":"alimir71@gmail.com"}],"homepage":"https://github.com/Alimir/wp-toolkit#readme","bugs":{"url":"https://github.com/Alimir/wp-toolkit/issues"},"bin":{"wp-toolkit":"bin/wp-toolkit.mjs"},"dist":{"shasum":"93a11e65b35011b9435c056d37145435ab855a61","tarball":"https://registry.npmjs.org/@alimir/wp-toolkit/-/wp-toolkit-1.1.3.tgz","fileCount":24,"integrity":"sha512-KzIi1jN2Z3sfChf72L5uq1eLd6Rqf3WR+f9eIJTx4wUw6s1bLGkZ5WaS8oCdr6aj0xkfSPEgZVpdiApvQqFM2w==","signatures":[{"sig":"MEQCIAvL9oLVJT/3yAph90gAeTmjmB3LdUjugEvmNNvV0MT+AiAKVZUNz2jhascYdggrYYeUGkbm6NZ509mmfBvKJlSwzQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":62549},"type":"module","engines":{"node":">=18"},"exports":{".":"./src/context.mjs"},"gitHead":"463b97cba74fbc8a1ef7ac104fe075a725c1963b","scripts":{"test":"node bin/wp-toolkit.mjs"},"_npmUser":{"name":"alimir","email":"alimir71@gmail.com"},"deprecated":"v2.0.0 requires new config. See CHANGELOG.md","repository":{"url":"git+https://github.com/Alimir/wp-toolkit.git","type":"git"},"_npmVersion":"10.8.2","description":"npm-based build and deploy toolkit for WordPress plugins — compile assets, package releases, rsync deploy, and optional WordPress.org SVN publish.","directories":{},"_nodeVersion":"20.19.4","dependencies":{"sass":"^1.89.2","terser":"^5.43.1","chokidar":"^4.0.3","preprocess":"^3.2.0","lightningcss":"^1.29.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/wp-toolkit_1.1.3_1781608086345_0.30714653440232587","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@alimir/wp-toolkit","version":"2.0.0","keywords":["wordpress","wordpress-plugin","build","deploy","grunt","sass","wordpress-org","svn","rsync"],"author":{"url":"https://wpulike.com","name":"TechnoWich","email":"wpulike@gmail.com"},"license":"MIT","_id":"@alimir/wp-toolkit@2.0.0","maintainers":[{"name":"alimir","email":"alimir71@gmail.com"}],"homepage":"https://www.npmjs.com/package/@alimir/wp-toolkit","bugs":{"url":"https://github.com/Alimir/wp-toolkit/issues"},"bin":{"wp-toolkit":"bin/wp-toolkit.mjs"},"dist":{"shasum":"9416739ef1ef2e748ffe3a8314c04443f7911557","tarball":"https://registry.npmjs.org/@alimir/wp-toolkit/-/wp-toolkit-2.0.0.tgz","fileCount":25,"integrity":"sha512-/SDw9oburr1N9tj1Kv3sJNOcpzxD5iz9LkDh3faWZi1x3x1HnuaOkh30cIIRNv7dgpz17xoRVOx+j6Qi0B4QOw==","signatures":[{"sig":"MEQCIHHGj9VUfMZ/ObOUXrGMUIVW1KV4gxw2LOVsQ7qbmZS2AiA6dhkZR+aOFxYZudXSlp+cV7A3Hsi0G4c5NSWlQ0ccKw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":73094},"type":"module","engines":{"node":">=18"},"exports":{".":"./src/context.mjs"},"gitHead":"bb90fc583cb0fb88f8118a88aa023228584ce3a6","scripts":{"test":"node bin/wp-toolkit.mjs"},"_npmUser":{"name":"alimir","email":"alimir71@gmail.com"},"repository":{"url":"git+https://github.com/Alimir/wp-toolkit.git","type":"git"},"_npmVersion":"10.8.2","description":"npm-based build and deploy toolkit for WordPress plugins — compile assets, package releases, rsync deploy, and optional WordPress.org SVN publish.","directories":{},"_nodeVersion":"20.19.4","dependencies":{"sass":"^1.89.2","terser":"^5.43.1","chokidar":"^4.0.3","preprocess":"^3.2.0","lightningcss":"^1.29.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/wp-toolkit_2.0.0_1781700447135_0.5060516226365774","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"name":"@alimir/wp-toolkit","version":"2.0.1","description":"npm-based build and deploy toolkit for WordPress plugins — compile assets, package releases, rsync deploy, and optional WordPress.org SVN publish.","type":"module","bin":{"wp-toolkit":"bin/wp-toolkit.mjs"},"exports":{".":"./src/context.mjs"},"publishConfig":{"access":"public"},"scripts":{"test":"node bin/wp-toolkit.mjs"},"keywords":["wordpress","wordpress-plugin","build","deploy","grunt","sass","wordpress-org","svn","rsync"],"author":{"name":"TechnoWich","email":"wpulike@gmail.com","url":"https://wpulike.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Alimir/wp-toolkit.git"},"bugs":{"url":"https://github.com/Alimir/wp-toolkit/issues"},"homepage":"https://www.npmjs.com/package/@alimir/wp-toolkit","engines":{"node":">=18"},"dependencies":{"chokidar":"^4.0.3","lightningcss":"^1.29.3","preprocess":"^3.2.0","sass":"^1.89.2","terser":"^5.43.1"},"_id":"@alimir/wp-toolkit@2.0.1","gitHead":"8468c6ba44ad328cc94ee950e568d81251b7cc2a","_nodeVersion":"20.19.4","_npmVersion":"10.8.2","dist":{"integrity":"sha512-WmbSzoEUAq0KFPj96NJwfnK/bKJ08TWReUQSbjOhoxy8A0YrKyoj+To/fWo6qnBs+w05RmLMiBqX2Kl7F90hAA==","shasum":"e33c4251af248eaade868577dd9c6dd4f158b20e","tarball":"https://registry.npmjs.org/@alimir/wp-toolkit/-/wp-toolkit-2.0.1.tgz","fileCount":25,"unpackedSize":74496,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIA7WCX7KyCWLjMBuUHo1YOUIXLQu1raa6vvdHakkEG79AiBzpxp4p7O9mjaRTzTOLNVXs9sgoy0vKkWOLMJFlUtdEQ=="}]},"_npmUser":{"name":"alimir","email":"alimir71@gmail.com"},"directories":{},"maintainers":[{"name":"alimir","email":"alimir71@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/wp-toolkit_2.0.1_1781701697565_0.08555467222157542"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-16T11:08:06.119Z","modified":"2026-06-17T13:08:17.832Z","1.1.3":"2026-06-16T11:08:06.482Z","2.0.0":"2026-06-17T12:47:27.275Z","2.0.1":"2026-06-17T13:08:17.718Z"},"bugs":{"url":"https://github.com/Alimir/wp-toolkit/issues"},"author":{"name":"TechnoWich","email":"wpulike@gmail.com","url":"https://wpulike.com"},"license":"MIT","homepage":"https://www.npmjs.com/package/@alimir/wp-toolkit","keywords":["wordpress","wordpress-plugin","build","deploy","grunt","sass","wordpress-org","svn","rsync"],"repository":{"type":"git","url":"git+https://github.com/Alimir/wp-toolkit.git"},"description":"npm-based build and deploy toolkit for WordPress plugins — compile assets, package releases, rsync deploy, and optional WordPress.org SVN publish.","maintainers":[{"name":"alimir","email":"alimir71@gmail.com"}],"readme":"# wp-toolkit\n\nnpm-based build and deploy toolkit for **any** WordPress plugin.\n\nCompile SCSS and JavaScript, package a production zip, rsync to your server, and optionally publish to WordPress.org SVN — all driven by one config file in your plugin.\n\nA modern, config-first alternative to Grunt.\n\n## Who is this for?\n\n- Plugin authors replacing Grunt / custom shell scripts\n- Teams that want one standard workflow across multiple plugins\n- Free plugins on WordPress.org **or** commercial / private plugins (SVN is optional)\n\n## Install\n\nIn your WordPress plugin root:\n\n```bash\nnpm install @alimir/wp-toolkit --save-dev\n```\n\nPackage: [@alimir/wp-toolkit on npm](https://www.npmjs.com/package/@alimir/wp-toolkit)\n\nWhile developing the toolkit itself, link it locally:\n\n```bash\nnpm install /path/to/wp-toolkit --save-dev\n```\n\n## Quick start\n\n**1. Create your plugin config** (this is where *your* paths and settings go):\n\n```bash\ncp node_modules/@alimir/wp-toolkit/wp-toolkit.config.example.mjs wp-toolkit.config.mjs\n```\n\nEdit `wp-toolkit.config.mjs` — set your slug, asset paths, deploy targets, and release options.\n\n**2. Add environment variables** (secrets never go in the config file):\n\n```bash\ncp node_modules/@alimir/wp-toolkit/.env.example .env\n```\n\n**3. Add npm scripts** to your plugin `package.json`:\n\n```json\n{\n  \"scripts\": {\n    \"build\": \"wp-toolkit build\",\n    \"build:js\": \"wp-toolkit build:js\",\n    \"build:css\": \"wp-toolkit build:css\",\n    \"dev\": \"wp-toolkit dev\",\n    \"i18n\": \"wp-toolkit i18n\",\n    \"i18n:json\": \"wp-toolkit i18n:json\",\n    \"product\": \"wp-toolkit product\",\n    \"release\": \"wp-toolkit release\"\n  },\n  \"devDependencies\": {\n    \"@alimir/wp-toolkit\": \"^2.0.1\"\n  }\n}\n```\n\n**4. Build:**\n\n```bash\nnpm run build\n```\n\nOutput lands in `build/<your-slug>/` plus `build/<your-slug>.zip`.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `wp-toolkit build` | Full production build + zip |\n| `wp-toolkit build:js` | Compile and minify JavaScript only |\n| `wp-toolkit build:css` | Compile SCSS and minify CSS only |\n| `wp-toolkit dev` | Watch SCSS/JS and rebuild on change |\n| `wp-toolkit deploy <name>` | Rsync `build/` to a configured server (default: `prod`) |\n| `wp-toolkit product [name]` | Build, then deploy (default: `prod`) |\n| `wp-toolkit release` | Build, then publish to WordPress.org SVN |\n| `wp-toolkit i18n` | Generate `.pot` file (requires WP-CLI) |\n| `wp-toolkit i18n:json` | Generate JSON from `.po` files |\n\n### Release safety flags\n\n```bash\nWP_RELEASE_DRY_RUN=1 npm run release   # preview SVN changes, no commit\nWP_RELEASE_YES=1 npm run release       # skip interactive confirmation\nWP_RELEASE_MESSAGE=\"Release 1.2.0\" npm run release\n```\n\n## Configuration\n\n**All plugin-specific settings live in `wp-toolkit.config.mjs`.** Every asset path is explicit — wp-toolkit does not guess filenames from your slug.\n\nThe config uses one **lifetime structure**. Required sections are validated on startup with clear errors when something is missing or invalid.\n\n### Config layout\n\n| Section | Required | Purpose |\n|---------|----------|---------|\n| **Identity** | yes | `slug`, `mainFile`, `textDomain` |\n| **`assets`** | yes | `js.bundles`, `css.sassEntries` (use `[]` / `{}` when unused) |\n| **`build`** | yes | `excludes` and release packaging options |\n| **`release`** | no | WordPress.org SVN (`enabled: true` + `svnUrl`) |\n| **`deploy`** | no | Rsync targets for commercial / private plugins |\n| **`i18n`** | no | POT generation (`domain` + `potFile` when present) |\n| **`variants`** | no | Alternate builds (regional, white-label, …) |\n\n### Level 1 — Every plugin (start here)\n\n```js\nexport default {\n  slug: 'my-plugin',\n  mainFile: 'my-plugin.php',\n  textDomain: 'my-plugin',\n\n  assets: {\n    js: {\n      bundles: [\n        {\n          sources: ['assets/js/src/app.js'],\n          output: 'assets/js/my-plugin.js',\n          minOutput: 'assets/js/my-plugin.min.js',\n        },\n      ],\n    },\n    css: {\n      sassEntries: {\n        'assets/css/my-plugin.css': 'assets/sass/my-plugin.scss',\n      },\n    },\n  },\n\n  build: {\n    excludes: ['assets/sass', 'assets/js/src'],\n  },\n\n  // WordPress.org:\n  release: { enabled: true, svnUrl: 'https://plugins.svn.wordpress.org/my-plugin' },\n\n  // Commercial / private:\n  // release: { enabled: false },\n  // deploy: { prod: { envPrefix: 'DEPLOY_PROD' } },\n};\n```\n\n```bash\nnpm run build      # → build/my-plugin.zip\nnpm run dev        # watch assets\nnpm run release    # WP.org only\nnpm run product    # deploy only\n```\n\n`validation.inheritExcludes` is **on by default** — paths in `build.excludes` are automatically blocked from release zips.\n\n### Level 2 — Optional extras (only if you need them)\n\n**Version in zip + versioned zip name** (commercial plugins):\n\n```js\nbuild: {\n  zipName: '{slug}.{version}.zip',\n  versionFile: { enabled: true, includeInZip: true },\n},\n```\n\n**Deploy to multiple servers** — add a name, add matching `.env` vars:\n\n```js\ndeploy: {\n  prod: { envPrefix: 'DEPLOY_PROD' },\n  staging: { envPrefix: 'DEPLOY_STAGING' },\n},\n```\n\n```bash\nwp-toolkit product staging\n```\n\n**Pre/post build hooks** — run your own commands as part of `wp-toolkit build`:\n\n```js\nbuild: {\n  hooks: {\n    preBuild: ['npm run codegen'],\n    postBuild: ['npm run notify:slack'],\n  },\n},\n```\n\nHooks accept shell strings or objects:\n\n```js\n{ command: 'node', args: ['scripts/generate.php'], cwd: 'tools' }\n```\n\n### Level 3 — Alternate builds (variants)\n\nUse when you need a **second build** with different strings or zip name.  \n**Deploy on a variant is optional** — omit it for build-only variants.\n\n```js\nvariants: {\n  regional: {\n    zipSuffix: '-regional',\n    replacements: [{ from: 'example.com', to: 'example.ir' }],\n    files: ['**/*.php'],\n    deploy: 'staging',   // optional — name from deploy.{name} above\n  },\n},\n```\n\n```bash\nwp-toolkit build --variant regional\nwp-toolkit product --variant regional   # build + deploy (uses variant.deploy)\n```\n\nAdd custom npm scripts for convenience:\n\n```json\n\"build:regional\": \"wp-toolkit build --variant regional\",\n\"product:regional\": \"wp-toolkit product --variant regional\"\n```\n\n### Config reference\n\n| Option | Purpose |\n|--------|---------|\n| `slug` | Plugin folder name, zip name, deploy path |\n| `mainFile` | Main plugin PHP file |\n| `textDomain` | Translation text domain |\n| `assets.js.bundles` | JS bundles — each needs `sources`, `output`, `minOutput` |\n| `assets.js.minify` | Standalone minify targets (`{ input, output }`) |\n| `assets.css.sassEntries` | SCSS input → CSS output map |\n| `assets.css.minifySeparate` | Keep unminified `.css` alongside `.min.css` |\n| `assets.watch` | Extra directories to watch in `dev` |\n| `build.excludes` | Paths excluded from `build/` |\n| `build.devOnlyFiles` | Files stripped from the production zip |\n| `build.preprocess` | Flags for `/* @if PRO */` conditional blocks |\n| `build.hooks` | `preBuild` and `postBuild` shell commands |\n| `build.zipName` | Zip filename template (`{slug}`, `{version}`, …) |\n| `build.versionFile` | Write a version txt beside or inside the zip |\n| `build.trimTrailingWhitespace` | Strip trailing spaces/tabs from text files in the release bundle (default: `true`) |\n| `deploy` | Named rsync targets (`prod`, `staging`, …) |\n| `release` | WordPress.org SVN (`enabled: true` requires `svnUrl`) |\n| `i18n` | POT generation (`domain`, `potFile`) |\n| `validation.inheritExcludes` | Merge `build.excludes` into release checks (default: `true`) |\n| `validation.forbidden` | Extra paths that must not appear in a release zip |\n| `validation.checkMinifiedAssets` | Warn if PHP enqueues unminified assets (default: `true`) |\n\n### WordPress.org plugins\n\nIn `wp-toolkit.config.mjs`:\n\n```js\nrelease: {\n  enabled: true,\n  wpAssets: 'wp-assets',\n  svnUrl: 'https://plugins.svn.wordpress.org/my-plugin',\n},\n```\n\nIn `.env`:\n\n```\nWP_SVN_USER=your-wordpress-org-username\nWP_SVN_PASSWORD=your-application-password\nWP_SVN_URL=https://plugins.svn.wordpress.org/my-plugin\n```\n\nRelease behaviour:\n\n- Sparse SVN checkout (fast; avoids flooding output with old tags)\n- Blocks re-releasing the same version tag\n- Asks you to type `yes` before committing\n\n### Commercial / private plugins\n\n```js\nrelease: { enabled: false },\ndeploy: { prod: { envPrefix: 'DEPLOY_PROD' } },\n```\n\n```bash\nnpm run product\n```\n\n### Advanced (power users)\n\n<details>\n<summary>Multiple JS bundles, custom rsync, inline variant deploy</summary>\n\n**Multiple JS bundles** — add more entries under `assets.js.bundles`:\n\n```js\nassets: {\n  js: {\n    bundles: [\n      { sources: ['assets/js/src/app.js'], output: 'assets/js/my-plugin.js', minOutput: 'assets/js/my-plugin.min.js' },\n      { sources: ['admin/assets/js/src/admin.js'], output: 'admin/assets/js/admin.js', minOutput: 'admin/assets/js/admin.min.js' },\n    ],\n  },\n},\n```\n\n**Custom rsync args** — add to any deploy target:\n\n```js\ndeploy: {\n  staging: {\n    envPrefix: 'DEPLOY_STAGING',\n    rsync: { args: ['-avzP', '--delete-after'] },\n  },\n},\n```\n\n**Variant deploy override** — only if you need different rsync per variant:\n\n```js\nvariants: {\n  regional: {\n    deploy: { target: 'staging', rsync: { args: ['-avzP', '--delete-after'] } },\n  },\n},\n```\n\n</details>\n\n## Environment variables\n\nCopy `.env.example` to `.env` in your plugin root. Never commit `.env`.\n\nDeploy target names in config use `envPrefix`. That prefix becomes your `.env` keys:\n\n| Config | `.env` keys |\n|--------|-------------|\n| `deploy.prod.envPrefix: 'DEPLOY_PROD'` | `DEPLOY_PROD_HOST`, `DEPLOY_PROD_DEST`, `DEPLOY_PROD_PORT` |\n\n| Variable | Used by |\n|----------|---------|\n| `DEPLOY_<NAME>_HOST` | Rsync SSH host |\n| `DEPLOY_<NAME>_PORT` | SSH port (optional) |\n| `DEPLOY_<NAME>_DEST` | Remote plugin directory (absolute path) |\n| `WP_SVN_USER` | WordPress.org SVN username |\n| `WP_SVN_PASSWORD` | WordPress.org application password |\n| `WP_SVN_URL` | SVN repository URL |\n| `WP_RELEASE_DRY_RUN` | Preview release without committing |\n| `WP_RELEASE_YES` | Skip confirmation prompt |\n| `WP_RELEASE_MESSAGE` | Custom SVN commit message |\n\n## Requirements\n\n- Node.js 18+\n- `zip` and `rsync` on `PATH`\n- `svn` — only for WordPress.org release\n- `wp` (WP-CLI) — only for `i18n` commands\n- Optional: `pngquant`, `jpegoptim` for image compression during build\n\n## Project layout\n\n```\nyour-plugin/\n├── wp-toolkit.config.mjs   ← your plugin settings (commit this)\n├── .env                    ← secrets (gitignored)\n├── package.json\n├── assets/\n├── build/                  ← generated (gitignored)\n└── node_modules/\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}