{"id":13740067,"url":"https://github.com/codemix/babel-plugin-trace","last_synced_at":"2025-05-14T09:31:41.882Z","repository":{"id":66017872,"uuid":"48203830","full_name":"codemix/babel-plugin-trace","owner":"codemix","description":"This is a Babel plugin which adds a straightforward, declarative syntax for adding debug logging to JavaScript applications.","archived":false,"fork":false,"pushed_at":"2018-05-30T10:43:34.000Z","size":19,"stargazers_count":63,"open_issues_count":1,"forks_count":6,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-11-01T16:42:59.665Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/codemix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-12-17T23:30:06.000Z","updated_at":"2024-02-23T19:57:24.000Z","dependencies_parsed_at":"2023-03-04T20:45:21.382Z","dependency_job_id":null,"html_url":"https://github.com/codemix/babel-plugin-trace","commit_stats":{"total_commits":14,"total_committers":3,"mean_commits":4.666666666666667,"dds":0.2857142857142857,"last_synced_commit":"878176022eb4c00d05988dfb4f5ae038a59306f2"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codemix%2Fbabel-plugin-trace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codemix%2Fbabel-plugin-trace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codemix%2Fbabel-plugin-trace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codemix%2Fbabel-plugin-trace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codemix","download_url":"https://codeload.github.com/codemix/babel-plugin-trace/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224758275,"owners_count":17364974,"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":[],"created_at":"2024-08-03T04:00:42.058Z","updated_at":"2024-11-15T09:31:01.050Z","avatar_url":"https://github.com/codemix.png","language":"JavaScript","funding_links":[],"categories":["Plugins","Macros"],"sub_categories":["Syntax Sugar","Development"],"readme":"# Babel Plugin: Trace\n\nThis is a [Babel](https://babeljs.io/) plugin \u0026 macro which adds a straightforward, declarative syntax for adding debug logging to JavaScript applications.\n\n[![Build Status](https://travis-ci.org/codemix/babel-plugin-trace.svg)](https://travis-ci.org/codemix/babel-plugin-trace)\n\n## What?\n\nIt's common to insert `console.log()` statements to help keep track of the internal state of functions when writing tricky pieces of code. During development this is very useful, but it creates a lot of noise in the console, and when development of that particular piece of code is complete, the developer is likely to delete the `console.log()` calls. If we're lucky, they might leave comments in their place.\n\nThis is a tragedy - that logging information is extremely useful, not only is it helpful when fixing bugs, it's a great assistance for new developers (including yourself, 6 months from now) when getting to know a codebase.\n\nThis plugin repurposes JavaScript [LabeledStatements](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/label) like `log:` and `trace:` to provide a logging / tracing syntax which can be selectively enabled or disabled at the folder, file, or function level at build time. Normally, these labels are only used as targets for labeled `break` and `continue` statements.\n\nWhen disabled in production the logging statements are completely dropped out, incurring no overhead. The syntax looks like this:\n\n```js\n// login.js\n\nasync function authenticate (username, password) {\n  log: 'authenticating user', username;\n  const user = await db.select().from('users').where({username: username});\n  if (!user) {\n    log: 'no such user';\n    return false;\n  }\n  else if (!user.checkPassword(password)) {\n    log: ({ password: 'invalid' })\n    return false;\n  }\n  else if (!user.isActive) {\n    log: 'user is not active';\n    return false;\n  }\n  log: 'logging user', username, 'into the site';\n  return true;\n}\n```\n\nThis will produce output like:\n\n```\nlogin:authenticate: authenticating user Bob\nlogin:authenticate:   no such user\nlogin:authenticate: authenticating user Alice\nlogin:authenticate:   invalid password\nlogin:authenticate: authenticating user Alice\nlogin:authenticate: logging user Alice into the site\n```\n\nAs well as `log:`, you can also use `trace:` and `warn:`, or specify your own using the `aliases` plugin option. By default all `trace:` logs will be stripped (unless specifically enabled) and `warn:` will use `console.warn` rather than `console.log`.\n\n## Installation\n\nInstall via [npm](https://npmjs.org/package/babel-plugin-trace).\n```\nnpm install --save-dev babel-plugin-trace\n```\n\n## Plugin Configuration\n\nIn your Babel configuration, add `\"trace\"` to your list of plugins. The default configuration will strip all logging from production builds, as well as trace logging from development and test environment, corresponding to this configuration:\n```json\n{\n  \"plugins\": [\n    [\"trace\", {\n      \"strip\": {\n        \"log\": { \"production\": true },\n        \"trace\": true,\n        \"warn\": { \"production\": true }\n      }\n    }]\n  ]\n}\n```\n\n`\"strip\"` may also take a `true` value to disable all logging by default. In this case you can still enable it for certain files or functions using environment variables:\n```json\n{\n  \"plugins\": [\n    [\"trace\", { \"strip\": true }]\n  ]\n}\n```\n\n## Macro Configuration\n\nAs an alternative to use as a plugin, `babel-plugin-trace/macro` is provided for use together with [babel-plugin-macros](https://github.com/kentcdodds/babel-plugin-macros). This is relevant in particular if you're working with a [create-react-app](https://github.com/facebook/create-react-app) project, as that does not otherwise allow for Babel plugins to be used. With macro use, you'll need to import the macro in every file where you'd like to enable logging:\n\n```js\nimport initTrace from 'babel-plugin-trace/macro'\ninitTrace()\nlog: 'This is', { a: 'message' }\nwarn: ({ this: 'a warning' }) // parentheses are required if the first value is an { object }\n```\n\nTo customise the logging labels, import them as named imports of the macro (the default import is still required, as the labels don't really match the imported variable bindings):\n\n```js\nimport initTrace, { log, announce } from 'babel-plugin-trace/macro'\ninitTrace()\nannounce: 'This is', { an: 'announcement' }\nwarn: 'This is not logged as a warning'\n```\n\nA source reference to the default export [is required](https://github.com/kentcdodds/babel-plugin-macros/pull/65) to trigger the macro; it will be removed during transpilation.\n\n## Environment Variables\n\n### `TRACE_LEVEL` - Enable only specific logging levels\nLog only `warn` statements.\n```\nTRACE_LEVEL=warn babel -d ./lib ./src\n```\n\nLog `trace` and `warn` statements.\n```\nTRACE_LEVEL=trace,warn babel -d ./lib ./src\n```\n\n### `TRACE_FILE` - Enable by filename\nEnable logging for any file with `login.js` in the path.\n```\nTRACE_FILE=login.js babel -d ./lib ./src\n```\n\nEnable logging for any file with `db/models` or `components/login` in the path.\n```\nTRACE_FILE=db/models,components/login babel -d ./lib ./src\n```\n\n### `TRACE_CONTEXT` - Enable for specific functions\nEnable logging for any function called `login()` or `logout()`.\n```\nTRACE_CONTEXT=:login,:logout babel -d ./lib ./src\n```\n\nEnable logging for any function in a class called `User`.\n```\nTRACE_CONTEXT=:User: babel -d ./lib ./src\n```\n\n## License\n\nPublished by [codemix](http://codemix.com/) under a permissive MIT License, see [LICENSE.md](./LICENSE.md).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodemix%2Fbabel-plugin-trace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodemix%2Fbabel-plugin-trace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodemix%2Fbabel-plugin-trace/lists"}