Project starts on 30-10-2023
Visit the GitHub Page for better reading experience and latest docs. π
Shout out to hoangnhan2ka3 for providing a πͺwonderful issue report and a demo site.
*:pt-4
)More tests
customTailwindDarkModeSelector
option, the dark mode selector will be automatically obfuscated at full obfuscation.includeAnyMatchRegexes
and excludeAnyMatchRegexes
options into whiteListedFolderPaths
and blackListedFolderPaths
options. (Directly move the regexes to the whiteListedFolderPaths
and blackListedFolderPaths
options)removeOriginalCss
option, default to false
. Set to true
to delete original CSS from CSS files if it has a obfuscated version.classIgnore
option now supports Regex.This version is deeply inspired by PostCSS-Obfuscator. Shout out to n4j1Br4ch1D for creating such a great package and thank you tremor for sponsoring this project.
next-css-obfuscator.config.cjs
PostCSS-Obfuscator
anymore)Give me a β if you like it.
removeOriginalCss
option is set to true
?enableJsAst
?Because in the current version of PostCSS-Obfuscator does not work with Next.js. (see this issue for more details)
PostCSS-Obfuscator
will not edit the build files instead it will create a new folder and put the obfuscated source code files in it. This is where the issue is. Next.js will not recognize the obfuscated files and will not include them in the build. I tried to point Nextjs to build the obfuscated files (by simply changing the obfuscated source code folder to src
) but it didn't work.
Edit the build files directly. (It may not be the best solution but it works.)
[!IMPORTANT]\ This package is NOT guaranteed to work with EVERYONE. Check the site carefully before using it in production.
[!IMPORTANT]\ As a trade-off, the obfuscation will make your CSS files larger.
Environment | Version |
---|---|
OS | Windows 11 & Ubuntu 22.04 |
Node.js | v.18.17.1 |
NPM | v.10.1.0 |
Next.js (Page Router) | v.13.5.4 & v.13.4.1 |
Next.js (App Router) | v.14.0.4 |
TailwindCSS | v.3.3.3 |
(Theoretically it supports all CSS frameworks but I only tested it with TailwindCSS.)
npm install -D next-css-obfuscator
Visit the npm page.
Create and add the following code to next-css-obfuscator.config.cjs
or next-css-obfuscator.config.ts
:
module.exports = {
enable: true,
mode: "random", // random | simplify | simplify-seedable
refreshClassConversionJson: false, // recommended set to true if not in production
allowExtensions: [".jsx", ".tsx", ".js", ".ts", ".html", ".rsc"],
};
module.exports = {
enable: true,
mode: "random", // random | simplify | simplify-seedable
refreshClassConversionJson: false, // recommended set to true if not in production
allowExtensions: [".jsx", ".tsx", ".js", ".ts", ".html", ".rsc"],
enableMarkers: true,
};
import { Options } from "next-css-obfuscator";
module.exports = {
// other options ...
} as Options;
Feel free to checkout π Config Options Reference for more options and details.
[!NOTE] The obfuscation will never work as expected, tweak the options with your own needs.
Add the following code to package.json
:
"scripts": {
// other scripts ...
"obfuscate-build": "next-css-obfuscator"
},
Read π» CLI for more details.
npm run build
to build the project.npm run obfuscate-build
to obfuscate the css files.(You may need to delete the .next/cache
folder before running npm run start
to make sure the obfuscation takes effect. And don't forget to shift + F5
refresh the page.`)
[!WARNING]\ NEVER run
obfuscate-build
twice in a row. It may mess up the build files and the obfuscation conversion table. You can remove theclassConversionJsonFolderPath
(default:css-obfuscator
) folder to reset the conversion table.[!NOTE]\ For better development experience, it is recommended to enable
refreshClassConversionJson
option innext-css-obfuscator.config.cjs
and disable it in production.
For convenience, you may update your build script to:
// package.json
"scripts": {
// other scripts ...
"build": "next build && npm run obfuscate-build"
},
to make sure the build is always obfuscated and no need to run obfuscate-build
manually.
[!NOTE]\ It is a good idea to add the
/css-obfuscator
folder to.gitignore
to prevent the conversion table from being uploaded to the repository.
To partially obfuscate your project, you have to add the obfuscate marker class to the components you want to obfuscate.
// example
export default function HomePage() {
return (
<main className="flex min-h-screen flex-col items-center justify-center bg-gradient-to-b from-[#fac3e3] to-[#5c9cbd] text-white">
<div className="container flex flex-col items-center justify-center gap-12 px-4 py-16 ">
<h1 className="text-5xl font-extrabold tracking-tight text-white sm:text-[5rem]">
Next14 App Router
</h1>
</div>
- <div className="container flex flex-col items-center justify-center gap-12 px-4 py-16 ">
+ <div className="next-css-obfuscation container flex flex-col items-center justify-center gap-12 px-4 py-16 ">
<span className="text-2xl font-extrabold tracking-tight text-gray-700 border-2 border-blue-950 rounded-lg p-4">
My classes are obfuscated
</span>
</div>
</main>
);
}
See Next 14 App Router Partially Obfuscated Demo for more details.
If you are interested in my setting (from my production site), here it is
// next-css-obfuscator.config.cjs
module.exports = {
enable: true,
mode: "random", // random | simplify | simplify-seedable
refreshClassConversionJson: false, // recommended set to true if not in production
allowExtensions: [".jsx", ".tsx", ".js", ".ts", ".html", ".rsc"],
blackListedFolderPaths: [
"./.next/cache",
/\.next\/server\/pages\/api/,
/_document..*js/,
/_app-.*/,
/__.*/, // <= maybe helpful if you are using Next.js Lcal Fonts [1*]
],
};
[*1] See this comment
It may not be the best setting but it works for me. :)
Option | Type | Default | Description |
---|---|---|---|
enable | boolean | true | Enable or disable the obfuscation. |
mode | "random" | "simplify" | "simplify-seedable" | "random" | Obfuscate mode, random: Fixed size random class name simplify: Alphabetic class name, like medium simplify-seedable: Random dynamic size class name |
buildFolderPath | string | "./.next" | The folder path to store the build files built by Next.js. |
classConversionJsonFolderPath | string | "./css-obfuscator" | The folder path to store the before obfuscate and after obfuscated classes conversion table. |
refreshClassConversionJson | boolean | false | Refresh the class conversion JSON file(s) at every obfuscation. Good for setting tweaking but not recommended for production. |
classLength | number | 5 | The length of the obfuscated class name if in random mode. It is not recommended to set the length to less than 4. |
classPrefix | string | "" | The prefix of the obfuscated class name. |
classSuffix | string | "" | The suffix of the obfuscated class name. |
classIgnore | (string | Regex)[ ] | [ ] | The class names to be ignored during obfuscation. |
allowExtensions | string[ ] | [".jsx", ".tsx", ".js", ".ts", ".html", ".rsc"] | The file extensions to be processed. |
contentIgnoreRegexes | RegExp[ ] | [/.jsxs)("\w+"/g] | The regexes to match the content to be ignored during obfuscation. |
whiteListedFolderPaths | (string | Regex)[ ] | [ ] | The folder paths/Regex to be processed. Empty array means all folders will be processed. |
blackListedFolderPaths | (string | Regex)[ ] | [ ] | The folder paths/Regex to be ignored. |
enableMarkers | boolean | false | Enable or disable the obfuscation markers. |
markers | string[ ] | [ ] | Classes that indicate component(s) need to obfuscate. |
removeMarkersAfterObfuscated | boolean | true | Remove the obfuscation markers from HTML elements after obfuscation. |
removeOriginalCss | boolean | false | Delete original CSS from CSS files if it has a obfuscated version. (NOT recommended using in partial obfuscation) |
generatorSeed | string | "-1" | The seed for the random class name generator. "-1" means use random seed. For "random" and "simplify-seedable" mode only. |
logLevel | "debug" | "info" | "warn" | "error" | "success" | "info" | The log level. |
Option | Type | Default | Description | Stage |
---|---|---|---|---|
enableJsAst | boolean | false | Whether to obfuscate JS files using abstract syntax tree parser. contentIgnoreRegexes option will be ignored if this option is enabled. |
Alpha |
[!NOTE]\ The above options are still at the early stages of development and may not work as expected.
Open an issue if you encounter any issues.
[!NOTE]\ Stages -
- PoC: Proof of Concept. The feature is still in the concept stage and is not recommended in production.
- Alpha: The feature is still in the early stage of development and may not work as expected.
- Beta: The feature is almost completed and should work as expected but may have some issues. (if no issue is reported in a period, it will be considered stable.)
- Stable: The feature is in the final stage of development and should work as expected.
// next-css-obfuscator.config.cjs
module.exports = {
enable: true, // Enable or disable the plugin.
mode: "random", // Obfuscate mode, "random", "simplify" or "simplify-seedable"
buildFolderPath: ".next", // Build folder of your project.
classConversionJsonFolderPath: "./css-obfuscator", // The folder path to store the before obfuscate and after obfuscated classes conversion table.
refreshClassConversionJson: false, // Refresh the class conversion JSON file.
classLength: 5, // Length of the obfuscated class name.
classPrefix: "", // Prefix of the obfuscated class name.
classSuffix: "", // Suffix of the obfuscated class name.
classIgnore: [], // The class names to be ignored during obfuscation.
allowExtensions: [".jsx", ".tsx", ".js", ".ts", ".html", ".rsc"], // The file extensions to be processed.
contentIgnoreRegexes: [
/\.jsxs\)\("\w+"/g, // avoid accidentally obfuscate the HTML tag
], // The regexes to match the file content to be ignored during obfuscation.
whiteListedFolderPaths: [], // Only obfuscate files in these folders
blackListedFolderPaths: ["./.next/cache"], // Don't obfuscate files in these folders
enableMarkers: false, // Enable or disable the obfuscate marker classes.
markers: ["next-css-obfuscation"], // Classes that indicate component(s) need to obfuscate.
removeMarkersAfterObfuscated: true, // Remove the obfuscation markers from HTML elements after obfuscation.
removeOriginalCss: false, // Delete original CSS from CSS files if it has a obfuscated version.
generatorSeed: "-1", // The seed for the random generator. "-1" means use random seed.
//! Experimental feature
enableJsAst: false, // Whether to obfuscate JS files using abstract syntax tree parser (Experimental feature)
logLevel: "info", // Log level
};
next-css-obfuscator --config ./path/to/your/config/file
If you are using this package with Vercel, you may find the package does not work as expected after being updated. This is because Vercel will cache the last build for a faster build time. To fix this you have to redeploy with the Use existing build cache
option disabled.
Enable enableMarkers
and put the obfuscate marker class at every component included the index page. But if you want to set and forget, you must play with the options to ensure the obfuscation works as expected.
Your conversion table may be messed up. Try to delete the classConversionJsonFolderPath
(default: css-obfuscator
) folder to reset the conversion table.
removeOriginalCss
option is set to true
?In a normal situation, the package will only remove the original CSS that is related to the obfuscation and you should not see any CSS sharing the same declaration block.
You are not expected to see this:
/* example.css */
/* original form */
.text-stone-300 {
--tw-text-opacity: 1;
color: rgb(214 211 209 / var(--tw-text-opacity));
}
/* obfuscated form */
.d8964 {
--tw-text-opacity: 1;
color: rgb(214 211 209 / var(--tw-text-opacity));
}
But this:
/* example.css */
/* obfuscated form */
.d8964 {
--tw-text-opacity: 1;
color: rgb(214 211 209 / var(--tw-text-opacity));
}
If you encounter the first situation, it means something is wrong with the obfuscation. You may need to raise an issue with your configuration and the related code.
Since the original CSS may be referenced by other components not included in the obfuscation, the package will not remove the original CSS to prevent breaking the the site.
(I will take Vercel as an example)
You may discover that the obfuscated class conversion table updates every time you deploy your site to Vercel even if the refreshClassConversionJson
option is set to false
. As a result, the CSS file will update in every deployment and break the CDN cache. This is because Vercel will not keep the files generated by the previous deployment. To fix this, you can simply provide a fixed generatorSeed
to make sure the obfuscated class name will be the same as the previous.
enableJsAst
?If you are going to partially obfuscate your site, you may want to enable this option to obfuscate. It gives the ability to trace the variable that is related to the class name in a JS file which the normal basic partial obfuscation can't do. (WIP)
[!IMPORTANT] Note that if a shared component is under the obfuscation marker, that component will be obfuscated and may affect other components(with no obfuscation marker) that use the same shared component.
If you are going to obfuscate the whole site, you will get a way more accurate obfuscation by enabling this option without putting a ton of time into tweaking the options.
[!NOTE] As a trade-off, this will take more time to obfuscate.
[!NOTE] This method can only trace the variable within the same JS file. It can't trace the variable that is imported from another file.
tremor |
hoangnhan2ka3 |
Contributions are welcome! If you find a bug or have a feature request, please open an issue. If you want to contribute code, please fork the repository and run npm run test
before submit a pull request.
Are you using this package for a personal project? That's great! You can support us by starring this repo on Github βπβ.
Are you using this package within your organization and generating revenue from it? Fantastic! We depend on your support to continue developing and maintaining the package under an MIT License. You might consider showing your support through Github Sponsors.
This project is licensed under the MIT License - see the LICENSE file for details
Love it? Consider a donation to support my work.