{"id":16330880,"url":"https://github.com/amarcruz/jscc","last_synced_at":"2025-03-16T14:31:10.838Z","repository":{"id":52534186,"uuid":"44010951","full_name":"aMarCruz/jscc","owner":"aMarCruz","description":"Tiny and powerful preprocessor for conditional comments and replacement of compile-time variables in text files","archived":false,"fork":false,"pushed_at":"2021-08-25T00:39:31.000Z","size":245,"stargazers_count":52,"open_issues_count":3,"forks_count":7,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-04-29T20:21:47.502Z","etag":null,"topics":["comments","compilation","conditional","es6","html","javascript","jspreproc","parser","preprocessor","replacement","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aMarCruz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-10-10T13:05:56.000Z","updated_at":"2023-12-04T16:47:23.000Z","dependencies_parsed_at":"2022-09-17T08:01:32.512Z","dependency_job_id":null,"html_url":"https://github.com/aMarCruz/jscc","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aMarCruz%2Fjscc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aMarCruz%2Fjscc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aMarCruz%2Fjscc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aMarCruz%2Fjscc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aMarCruz","download_url":"https://codeload.github.com/aMarCruz/jscc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243818194,"owners_count":20352629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["comments","compilation","conditional","es6","html","javascript","jspreproc","parser","preprocessor","replacement","typescript"],"created_at":"2024-10-10T23:24:48.642Z","updated_at":"2025-03-16T14:31:09.914Z","avatar_url":"https://github.com/aMarCruz.png","language":"TypeScript","readme":"# jscc\n\n[![jscc on npm][npm-badge]][npm-url]\n[![License MIT][license-badge]][license-url]\n[![Linux Build][travis-badge]][travis-url]\n[![Codacy][codacy-badge]][codacy-url]\n[![Coverage][codecov-badge]][codecov-url]\n\nFeaturing some of the C preprocessor characteristics through special, configurable comments, jscc can be used in any type of files to build multiple versions of your software from the same code base.\n\nWith jscc, you have:\n\n- Conditional inclusion/exclusion of blocks, based on compile-time variables*\n- Compile-time variables with all the power of JavaScript expressions\n- Replacement of variables in the sources, by its value at compile-time\n- Sourcemap support, useful for JavaScript sources.\n- TypeScript v3 definitions\n\n\\* This feature allows you the conditional declaration of ES6 imports (See the [example](#example)).\n\njscc is derived on [jspreproc](http://amarcruz.github.io/jspreproc), the tiny source file preprocessor in JavaScript, enhanced with sourcemap support but without the file importer nor the removal of comments ([rollup](https://rollupjs.org/guide/en) with [rollup-plugin-cleanup](https://www.npmjs.com/package/rollup-plugin-cleanup) does it better).\n\njscc works in NodeJS 6 or later, with minimal dependencies and footprint. It was designed to operate on small to medium pieces of code (like most nowadays) and, since the whole process is done in memory, it is _really fast_.\n\njscc is **not** a minifier tool, but it does well what it does...\n\n## Install\n\nUse the instructions of the plugin for your toolchain:\n\n- [Rollup](https://www.npmjs.com/package/rollup-plugin-jscc)\n- [Brunch](https://www.npmjs.com/package/jscc-brunch)\n- [Browserify](https://www.npmjs.com/package/jsccify)\n- [Gulp](https://www.npmjs.com/package/gulp-jscc)\n- [WebPack](https://github.com/OrangeLab/webpack-plugin-jscc) - Thanks to @duanlikang\n\nor install the jscc package from npm if you need direct access to its API:\n\n```sh\nnpm i jscc -D\n```\n\n### Direct Usage\n\n```js\nconst jscc = require('jscc');\n\nconst result = jscc(sourceCode, options);\n\n// or in async mode:\njscc(sourceCode, options, (err, result) =\u003e {\n  if (err) {\n    console.error(err);\n  } else {\n    console.log(result.code);\n    console.log(result.map);\n  }\n})\n```\n\nThe result is a plain JS object with a property `code`, a string with the processed source, and a property `map`, with a raw sourcemap object, if required by the `sourcemap` option (its default is `true`).\n\nIf a callback is provided, jscc will operate asynchronously and call the callback with an error object, if any, or `null` in the first parameter and the result in the second.\n\nPlease see the Wiki to know the supported [options](https://github.com/aMarCruz/jscc/wiki/Options).\n\n## Directives\n\njscc works with _directives_ inserted in the text and prefixed with configurable character sequences, that defaults to `'/*'`, `'//'` and `'\u003c!--'`.\n\nThis directives allows you set or get compile-time variables, and exclude code blocks based in its value.\n\nHere, I will refer to the names of the compile-time variables as _varnames_, to distinguish them from the JavaScript run-time variables.\n\nTo be valid, a `\u003cvarname\u003e` must match the regular expression `/^_[0-9A-Z][_0-9A-Z]*$/`.\n\n\u003e That is, it must start with an underscore, followed by a digit or uppercase letter, and then zero or more underscores, digits or uppercase letters. The character `$` has a special use in jscc and is not allowed for varnames.\n\n### `#set \u003cvarname\u003e = \u003cvalue\u003e`\n\nDefines or redefines a `varname`.\n\nThe `value` can be a literal value, another varname, or an expression. If you don't specify a value, it is set to `undefined`.\n\n### `#unset \u003cvarname\u003e`\n\nRemoves the definition of the given `varname`.\n\nBoth the definition or removal of a varname take immediate effect.\n\n### `#if \u003cexpression\u003e`\n\nRemove the block of code that follows this `#if` if `expression` is _falsy_.\n\nYou can nest multiple `#if` blocks.\n\n### `#ifset \u003cvarname\u003e`\n\nCheck the existence of a `varname`.\n\nThe returned value is `true` if the variable exists, even if its value is `undefined`. Apart from this, the behavior of `#ifset` is the same as `#if`, so references to the latter will imply both.\n\n### `#ifnset \u003cvarname\u003e`\n\nThis is the opposite to `#ifset`, it returns `false` if the `varname` does not exists.\n\n### `#elif \u003cexpression\u003e`\n\nThe behavior of `#elif` is similar to the JS `else if` statement.\n\nThe `expression` will be evaluated if the previous `#if` or `#elif` was _falsy_.\n\nYou can have zero or more `#elif` directives following one `#if`.\n\n## `#else`\n\nIncludes the block that follows if the previous `#if` or `#elif` expressions were _falsy_.\n\n### `#endif`\n\nCloses the current conditional block.\n\n### `#error \u003cexpression\u003e`\n\nGenerates an exception at compile time with the result of the given character `expression`.\n\nYou can learn more about this in the [Wiki](https://github.com/aMarCruz/jscc/wiki).\n\n## Changes in This Version\n\n- Closes #8 : Removel of trailing jscc comment is breaking the expression.\n- Removed Codebeat tests.\n- More unity tests.\n\nSee details in the [Changelog](CHANGELOG.md).\n\n## Known Issues\n\n- If you are using ESM imports with Typescript, you must enable `esModuleInterop` in your tsconfig.json or use `import jscc = require(\"jscc\")`.\n- jscc does not work in a browser, but it must work without issues on the back-end.\n\n### ES6 TL\n\nRemember that jscc is language agnostic, the following block may or may not work as you think:\n\n```js\nconst template = `\n//#if _DEBUG\nconsole.log('debug mode is on.')\n//#endif\n`\nfs.writeFile('code.js', template, 'utf8')\n```\n\nDirective searching knows nothing about ES6 TL, so the `#if..#endif` within the template will be evaluated at compile-time, just like any other (code.js is written without directives).\n\n## TODO\n\n- [X] ~~Async mode~~ (v1.0.0)\n- [ ] Explanatory error messages, with location of the error\n- [ ] Different prefixes for different file types\n- [ ] Express middleware\n- [X] WebPack plugin\n- [ ] Better documentation\n- [ ] Syntax hilighter for some editores? Perhaps you want to contribute.\n\n## Support my Work\n\nI'm a full-stack developer with more than 20 year of experience and I try to share most of my work for free and help others, but this takes a significant amount of time, effort and coffee so, if you like my work, please consider...\n\n[\u003cimg src=\"https://amarcruz.github.io/images/kofi_blue.png\" height=\"36\" title=\"Support Me on Ko-fi\" /\u003e][kofi-url]\n\nOf course, feedback, PRs, and stars are also welcome 🙃\n\nThanks for your support!\n\n## License\n\nThe [MIT](LICENSE) License.\n\n\u0026copy; 2018, Alberto Martínez\n\n[![Windows Build][appveypr-badge]][appveypr-url]\n[![CodeClimate][climate-badge]][climate-url]\n[![Vulnerabilities][snyk-badge]][snyk-url]\n[![Last commit][commits-badge]][commits-url]\n\n\u003c!-- Badges --\u003e\n[npm-badge]:      https://img.shields.io/npm/v/jscc.svg\n[npm-url]:        https://www.npmjs.com/package/jscc\n[license-badge]:  https://img.shields.io/npm/l/jscc.svg?colorB=blue\n[license-url]:    https://github.com/aMarCruz/jscc/blob/master/LICENSE\n[appveypr-badge]: https://ci.appveyor.com/api/projects/status/hdsef0p6q0oqr127?svg=true\n[appveypr-url]:   https://ci.appveyor.com/project/aMarCruz/jscc\n[travis-badge]:   https://img.shields.io/travis/aMarCruz/jscc.svg?label=travis\n[travis-url]:     https://travis-ci.org/aMarCruz/jscc\n[snyk-badge]:     https://snyk.io/test/github/aMarCruz/jscc/badge.svg?targetFile=package.json\n[snyk-url]:       https://snyk.io/test/github/aMarCruz/jscc?targetFile=package.json\n[codacy-badge]:   https://img.shields.io/codacy/grade/30e8679fcd614227837ad250dd6c4030.svg\n[codacy-url]:     https://www.codacy.com/app/aMarCruz/jscc?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=aMarCruz/jscc\u0026amp;utm_campaign=Badge_Grade\n[codecov-badge]:  https://img.shields.io/codecov/c/github/aMarCruz/jscc.svg\n[codecov-url]:    https://codecov.io/gh/aMarCruz/jscc\n[climate-badge]:  https://codeclimate.com/github/aMarCruz/jscc/badges/gpa.svg\n[climate-url]:    https://codeclimate.com/github/aMarCruz/jscc\n[commits-badge]:  https://img.shields.io/github/last-commit/aMarCruz/jscc.svg\n[commits-url]:    https://github.com/aMarCruz/jscc/commits/master\n[kofi-url]:       https://ko-fi.com/C0C7LF7I\n","funding_links":["https://ko-fi.com/C0C7LF7I"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famarcruz%2Fjscc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famarcruz%2Fjscc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famarcruz%2Fjscc/lists"}