@castlenine/vite-remove-attribute 1.0.1 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## 2.0.0
+
+### Fixed
+
+- Ignore tokens were matched as substrings of the **absolute** module id, so a checkout path containing `build`, `dist`,
+  `public`, `logs`, `e2e`, `.cache` or `.env` (Cloudflare Workers clones into `/opt/buildhome/repo`) disabled the plugin
+  entirely. Tokens are now matched on path-segment boundaries against the path relative to the Vite root: `build`
+  matches `build/app.js` but no longer `buildhome/app.js`. Multi-segment tokens such as `src/tests` and
+  `src/components/Modal.svelte` keep working.
+- The expression form `attribute={…}` was never removed. Brace-balanced values, template literals and nested `${…}`
+  placeholders are now handled; an unbalanced expression is left untouched.
+- A bare attribute closing a self-closing tag (`<input data-testid />`) was not removed.
+- The `?query` suffix of a Vite module id is stripped before extension and ignore matching.
+- Attribute names and extensions are regex-escaped.
+- `transform` returns `null` when a module is skipped or unchanged instead of echoing the source back.
+
+### Added
+
+- Every transformed module now carries a sourcemap (generated in-house, the package still has no runtime dependency), so
+  the consumer's sourcemaps keep pointing at the original lines and columns.
+- `ignoreDefaults` option (default `true`) to opt out of the built-in ignore list.
+- `*` in an ignore token matches within a single path segment (`*.log`, `.env.*`, `*.stories.svelte`).
+- The `Options` type is exported.
+- `engines.node` is declared as `>=18.0.0`. The bundle targets ES2022, which Node 18 runs natively, so the plugin works
+  with every Vite version from 2 to 8 on any Node release those versions support from 18 upwards.
+- `CHANGELOG.md` ships in the npm tarball.
+
+### Changed
+
+- The package has been renamed from `@castlenine/vite-remove-attribute` to `@castlenine/vite-plugin-remove-attribute` to
+  align with the Vite plugin naming convention. Uninstall the old name, install the new one and update the import
+  specifier; the default export, the options and the behaviour documented above are otherwise the same.
+- The CommonJS entry moved from `dist/index.umd.cjs` to `dist/index.cjs`. `require()` still returns the plugin function
+  and `.default` is also available; the entry is typed by `dist/index.d.cts`.

package/LICENSE

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright (c) 2024 Alexandre "Castlenine"
+Copyright (c) 2024–2026, Alex "Castlenine"
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,98 +1,259 @@
 <div align="center">
 
-# `@castlenine/vite-remove-attribute`
+# `@castlenine/vite-plugin-remove-attribute`
 
 [![npm.badge]][npm] [![download.badge]][download]
 
-Vite plugin that allows the removal of specified attributes and supports a variety of options, including file extensions, attributes, ignored folders, and files.
+Vite plugin that allows the removal of specified attributes and supports a variety of options, including file
+extensions, attributes, ignored folders, and files.
 </div>
 
+# ⚠️ DEPRECATED ⚠️
+
+**This package (`@castlenine/vite-remove-attribute`) has been renamed to
+[@castlenine/vite-plugin-remove-attribute](https://www.npmjs.com/package/@castlenine/vite-plugin-remove-attribute) to
+follow Vite plugin naming conventions. Please use the new package. This package is now deprecated and will be removed in
+December 2027.**
+
 ## Table of Contents
 
+- [Disclaimer](#disclaimer)
 - [Features](#features)
+- [Requirements](#requirements)
 - [Installation](#installation)
 - [Usage](#usage)
   - [Prerequisites](#prerequisites)
-  - [Examples](#examples)
+  - [Notes](#notes)
+  - [Options](#options)
+  - [Ignore matching](#ignore-matching)
+  - [Sourcemaps](#sourcemaps)
+- [Examples](#examples)
+  - [SvelteKit](#sveltekit-example-1-removing-data-testid-attributes-from-svelte-files)
+  - [Vue.js](#vuejs-example-1-removing-data-testid-attributes-from-vue-files)
+  - [Opting out of the built-in ignore list](#opting-out-of-the-built-in-ignore-list)
+  - [CommonJS](#commonjs)
+- [Changelog](#changelog)
+- [Acknowledgement](#acknowledgement)
+- [License](#license)
+
+## Disclaimer
+
+**Only tested with Svelte, SvelteKit and Vue.js projects**. Please open an issue if you encounter any problems with
+other frameworks.
 
 ## Features
 
-- Removes specified attributes
+- Removes specified attributes in their quoted, expression (`={…}`) and bare forms
 - Allows you to specify the file extensions to be processed
 - Can ignore certain folders or files based on configuration
-- Ensures clean production code by removing unnecessary attributes, like 'data-testid' used in testing
+- Emits a sourcemap for every transformed file, so stack traces and debuggers keep pointing at the original code
+- Ensures clean production code by removing unnecessary attributes, like `data-testid` used in testing
+
+## Requirements
+
+| Requirement | Version                     |
+| ----------- | --------------------------- |
+| Node.js     | `>=18.0.0`                  |
+| Vite        | `>=2.0.0` (peer dependency) |
 
 ## Installation
 
-Use your package manager to install:
+Use your package manager to install it as a development dependency:
 
 ```shell
-npm i --save-dev @castlenine/vite-remove-attribute
+pnpm add -D @castlenine/vite-plugin-remove-attribute
+# or
+npm i -D @castlenine/vite-plugin-remove-attribute
+# or
+yarn add -D @castlenine/vite-plugin-remove-attribute
 ```
 
 ## Usage
 
 ### Prerequisites
 
-To use this plugin, you need to have a Vite project set up. Import and use the plugin in your `vite.config.js` or
-`vite.config.ts` file.
+To use this plugin, you must have a Vite config file set up in your project. If you don't have one, create a
+`vite.config.js` or `vite.config.ts` file in the root of your project.
+
+### Notes
+
+For some frameworks, like Svelte & SvelteKit, this plugin should be placed first (before the framework's plugin) in the
+`plugins` array and for others, like Vue.js, it should be placed after the framework's plugin.
+
+### Options
+
+| Option           | Type       | Default | Description                                                                                 |
+| ---------------- | ---------- | ------- | ------------------------------------------------------------------------------------------- |
+| `extensions`     | `string[]` | —       | File extensions to process, without the leading dot (e.g. `['svelte', 'vue']`)              |
+| `attributes`     | `string[]` | —       | Attribute names to remove (e.g. `['data-testid']`)                                          |
+| `ignoreFolders`  | `string[]` | `[]`    | Folders to skip, relative to the Vite root (e.g. `['src/tests']`)                           |
+| `ignoreFiles`    | `string[]` | `[]`    | Files to skip, relative to the Vite root (e.g. `['Header.svelte', 'src/lib/Modal.svelte']`) |
+| `ignoreDefaults` | `boolean`  | `true`  | Apply the built-in ignore list on top of `ignoreFolders` / `ignoreFiles`                    |
+
+The attribute is removed in its quoted form (`data-testid="a"`), its expression form (`data-testid={value}`, including
+template literals with nested `${…}`), its bare form (`<input data-testid />`) and with a Vue binding prefix
+(`:data-testid`, `v-bind:data-testid`). Matching is case-insensitive on the attribute name, and longer names such as
+`data-testid-extra` are left untouched.
+
+### Ignore matching
+
+Ignore tokens are matched against the module path **relative to the Vite root**, on path-segment boundaries: `build`
+matches `build/app.js` but not `buildhome/app.js`, and `src/tests` matches `src/tests/a.svelte` but not
+`src/tests-e2e/a.svelte`. A `*` matches any characters within a single segment (`*.stories.svelte`, `.env.*`).
+
+The built-in ignore list covers `node_modules`, `.git`, `.idea`, `.vscode`, `.DS_Store`, `Thumbs.db`, `.env`, `.env.*`,
+`logs`, `*.log`, `public`, `build`, `.svelte-kit`, `dist`, `.nuxt`, `.next`, `.remix`, `e2e`, `angular.json`,
+`browserslist` and `.cache`. Set `ignoreDefaults: false` to keep only your own tokens.
+
+### Sourcemaps
+
+Every transformed file returns a sourcemap (generated without any runtime dependency), so a `build.sourcemap` setting in
+your Vite config keeps mapping the generated code to the original lines and columns even when an attribute sat on its
+own line.
 
 ## Examples
 
-### Example 1: Removing 'data-testid' attributes from `.svelte` files
+### SvelteKit example 1: Removing 'data-testid' attributes from `.svelte` files
 
-This configuration will remove `data-testid` attributes from all `.svelte` files in the production build.
+This configuration will remove `data-testid` attributes from all `.svelte` files in the production build only.
 
 ```typescript
 import { defineConfig } from 'vite';
 import { sveltekit } from '@sveltejs/kit/vite';
 
-import removeAttribute from '@castlenine/vite-remove-attribute';
+import removeAttribute from '@castlenine/vite-plugin-remove-attribute';
+
+export default defineConfig(({ mode }) => ({
+	plugins: [
+		mode === 'production'
+			? removeAttribute({
+					extensions: ['svelte'],
+					attributes: ['data-testid'],
+				})
+			: null,
+
+		sveltekit(), // SvelteKit plugin should be placed after removeAttribute
+	],
+}));
+```
+
+### SvelteKit example 2: Ignoring specific folders and files
 
-const IS_PRODUCTION = process.env.NODE_ENV == 'production';
+This configuration will remove `data-testid` and `data-id` attributes from all `.svelte`, `.ts`, and `.js` files, with
+the exception of those located in the `src/tests` and `src/utilities` folders, as well as the `Header.svelte`,
+`src/components/Modal.svelte`, and `src/layouts/LayoutAuth.svelte` files in all builds.
+
+```typescript
+import { defineConfig } from 'vite';
+import { sveltekit } from '@sveltejs/kit/vite';
+
+import removeAttribute from '@castlenine/vite-plugin-remove-attribute';
 
 export default defineConfig({
-    plugins: [
-        sveltekit(),
-
-        IS_PRODUCTION
-            ? removeAttribute({
-                    extensions: ['svelte'],
-                    attributes: ['data-testid'],
-                })
-            : null,
-    ],
+	plugins: [
+		removeAttribute({
+			extensions: ['svelte', 'ts', 'js'],
+			attributes: ['data-testid', 'data-id'],
+			ignoreFolders: ['src/tests', 'src/utilities'],
+			ignoreFiles: ['Header.svelte', 'src/components/Modal.svelte', 'src/layouts/LayoutAuth.svelte'],
+		}),
+
+		sveltekit(), // SvelteKit plugin should be placed after removeAttribute
+	],
 });
 ```
 
-### Example 2: Ignoring specific folders and files
+### Vue.js example 1: Removing 'data-testid' attributes from `.vue` files
 
-This configuration will remove `data-testid` and `data-id` attributes from all `.svelte`, `.ts`, and `.js` files, with the exception of those located in the `src/tests` and `src/utilities` folders, as well as the `Header.svelte`, `src/components/Modal.svelte`, and `src/layouts/LayoutAuth.svelte` files in all builds.
+This configuration will remove `data-testid` attributes from all `.vue` files in the production build only.
 
 ```typescript
 import { defineConfig } from 'vite';
-import { sveltekit } from '@sveltejs/kit/vite';
+import vue from '@vitejs/plugin-vue';
+
+import removeAttribute from '@castlenine/vite-plugin-remove-attribute';
+
+export default defineConfig(({ mode }) => ({
+	plugins: [
+		vue(), // Vue plugin should be placed before removeAttribute
+		mode === 'production'
+			? removeAttribute({
+					extensions: ['vue'],
+					attributes: ['data-testid'],
+				})
+			: null,
+	],
+}));
+```
 
-import removeAttribute from '@castlenine/vite-remove-attribute';
+### Vue.js example 2: Ignoring specific folders and files
+
+This configuration will remove `data-testid` and `data-id` attributes from all `.vue`, `.ts`, and `.js` files, with the
+exception of those located in the `src/tests` and `src/utilities` folders, as well as the `Header.vue`,
+`src/components/Modal.vue`, and `src/layouts/LayoutAuth.vue` files in all builds.
+
+```typescript
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+
+import removeAttribute from '@castlenine/vite-plugin-remove-attribute';
 
 export default defineConfig({
-    plugins: [
-        sveltekit(),
-        removeAttribute({
-            extensions: ['svelte', 'ts', 'js'],
-            attributes: ['data-testid', 'data-id'],
-            ignoreFolders: ['src/tests', 'src/utilities'],
-            ignoreFiles: ['Header.svelte', 'src/components/Modal.svelte', 'src/layouts/LayoutAuth.svelte'],
-        }),
-    ],
+	plugins: [
+		vue(), // Vue plugin should be placed before removeAttribute
+		removeAttribute({
+			extensions: ['vue', 'ts', 'js'],
+			attributes: ['data-testid', 'data-id'],
+			ignoreFolders: ['src/tests', 'src/utilities'],
+			ignoreFiles: ['Header.vue', 'src/components/Modal.vue', 'src/layouts/LayoutAuth.vue'],
+		}),
+	],
 });
 ```
 
-<br />
+### Opting out of the built-in ignore list
+
+With `ignoreDefaults: false` only your own `ignoreFolders` / `ignoreFiles` tokens apply, so files under `public/` or
+`build/` are processed too.
+
+```typescript
+removeAttribute({
+	extensions: ['svelte'],
+	attributes: ['data-testid'],
+	ignoreDefaults: false,
+	ignoreFolders: ['node_modules'],
+});
+```
+
+### CommonJS
+
+The package also ships a CommonJS entry. `require()` returns the plugin function directly (`.default` is available as
+well):
+
+```javascript
+// vite.config.cjs
+const { defineConfig } = require('vite');
+const removeAttribute = require('@castlenine/vite-plugin-remove-attribute');
+
+module.exports = defineConfig({
+	plugins: [removeAttribute({ extensions: ['svelte'], attributes: ['data-testid'] })],
+});
+```
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).
+
+## Acknowledgement
+
+This project is a fork of [mustafadalga/remove-attr](https://github.com/mustafadalga/remove-attr). See
+[ACKNOWLEDGEMENT.md](./ACKNOWLEDGEMENT.md).
+
+## License
 
-Forked from [mustafadalga/remove-attr](https://github.com/mustafadalga/remove-attr)
+[MIT](./LICENSE)
 
-[npm]: https://www.npmjs.com/package/@castlenine/vite-remove-attribute
-[npm.badge]: https://img.shields.io/npm/v/@castlenine/vite-remove-attribute
-[download]: https://www.npmjs.com/package/@castlenine/vite-remove-attribute
-[download.badge]: https://img.shields.io/npm/d18m/@castlenine/vite-remove-attribute
+[npm]: https://www.npmjs.com/package/@castlenine/vite-plugin-remove-attribute
+[npm.badge]: https://img.shields.io/npm/v/@castlenine/vite-plugin-remove-attribute
+[download]: https://www.npmjs.com/package/@castlenine/vite-plugin-remove-attribute
+[download.badge]: https://img.shields.io/npm/d18m/@castlenine/vite-plugin-remove-attribute