{"id":49796058,"url":"https://github.com/startupjs/react-pug","last_synced_at":"2026-05-12T10:35:33.790Z","repository":{"id":342121235,"uuid":"1172924143","full_name":"startupjs/react-pug","owner":"startupjs","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-16T15:54:42.000Z","size":1185,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-16T17:35:39.305Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/startupjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-04T20:43:23.000Z","updated_at":"2026-04-16T15:54:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/startupjs/react-pug","commit_stats":null,"previous_names":["startupjs/react-pug"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/startupjs/react-pug","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/startupjs%2Freact-pug","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/startupjs%2Freact-pug/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/startupjs%2Freact-pug/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/startupjs%2Freact-pug/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/startupjs","download_url":"https://codeload.github.com/startupjs/react-pug/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/startupjs%2Freact-pug/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32934804,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-12T09:19:52.626Z","status":"ssl_error","status_checked_at":"2026-05-12T09:17:33.438Z","response_time":102,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":"2026-05-12T10:35:32.511Z","updated_at":"2026-05-12T10:35:33.785Z","avatar_url":"https://github.com/startupjs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# react-pug\n\nPug support for React in two parts:\n\n- VS Code IntelliSense inside `pug\\`...\\`` templates\n- Build/lint transforms for Babel, SWC, esbuild, and ESLint\n\n## Install\n\n### VS Code extension (build from this repo for now)\n\nFor now, clone the monorepo and run the following commands from the repository root:\n\n```bash\nnpm ci\nnpm run package:vsix\ncode --install-extension .tmp/vsix/vscode-react-pug-tsx.vsix\n```\n\nOr, to build and install in one step:\n\n```bash\nnpm ci\nnpm run install:vsix\n```\n\nThis builds the VSIX from the monorepo into `.tmp/vsix/`, keeps a stable install path at `.tmp/vsix/vscode-react-pug-tsx.vsix`, and installs it locally into VS Code.\n\nFor embedded editor support inside `style(...)` blocks:\n\n- `css` and `scss` work with built-in VS Code support\n- `styl` requires the VS Code extension `sysoev.language-stylus`\n- `sass` requires the VS Code extension `Syler.sass-indented`, since built-in VS Code CSS support does not handle indented Sass syntax\n\n### VS Code Marketplace\n\nTODO: publish `startupjs.vscode-react-pug-tsx` to the VS Code Marketplace.\n\nAfter that, installation by extension id will also work:\n\n```bash\ncode --install-extension startupjs.vscode-react-pug-tsx\n```\n\n## Runtime/Build Packages\n\nPublished package names:\n\n- `@react-pug/react-pug-core`\n- `@react-pug/typescript-plugin-react-pug`\n- `vscode-react-pug-tsx`\n- `@react-pug/babel-plugin-react-pug`\n- `@react-pug/swc-plugin-react-pug`\n- `@react-pug/esbuild-plugin-react-pug`\n- `@react-pug/eslint-plugin-react-pug`\n\n### Babel\n\n```js\n// babel.config.js\nmodule.exports = {\n  plugins: [\n    ['@react-pug/babel-plugin-react-pug', {\n      tagFunction: 'pug',\n      sourceMaps: 'basic',\n      requirePugImport: false,\n      classShorthandProperty: 'auto',\n      classShorthandMerge: 'auto',\n      startupjsCssxjs: 'auto',\n      componentPathFromUppercaseClassShorthand: true\n    }]\n  ]\n}\n```\n\nBabel source map modes:\n\n- `sourceMaps: 'basic'` (default) keeps Babel on the simple AST replacement path, replaces only matched `pug` tagged-template expressions during `Program` traversal, and produces coarse mappings for transformed Pug regions while leaving surrounding JS/TS mappings Babel-native.\n- `sourceMaps: 'detailed'` enables granular mappings back into Pug content by using Babel `parserOverride` plus an inline input source map. Use this when you care about devtools/debugger fidelity through later Babel transforms.\n\n### SWC (programmatic)\n\n```ts\nimport { transformWithSwcReactPug } from '@react-pug/swc-plugin-react-pug'\n\nconst result = transformWithSwcReactPug(sourceCode, fileName, {\n  jsc: {\n    parser: { syntax: 'typescript', tsx: true },\n    transform: { react: { runtime: 'automatic' } }\n  },\n  sourceMaps: true\n})\n```\n\n### esbuild\n\n```ts\nimport { build } from 'esbuild'\nimport { reactPugEsbuildPlugin } from '@react-pug/esbuild-plugin-react-pug'\n\nawait build({\n  entryPoints: ['src/index.tsx'],\n  bundle: true,\n  plugins: [reactPugEsbuildPlugin()],\n  sourcemap: true\n})\n```\n\n### ESLint processor\n\n```js\n// eslint.config.js (flat config)\nimport reactPugPlugin from '@react-pug/eslint-plugin-react-pug'\n\nexport default [\n  {\n    files: ['**/*.{js,jsx,ts,tsx}'],\n    plugins: { 'react-pug': reactPugPlugin },\n    processor: 'react-pug/react-pug'\n  }\n]\n```\n\nESLint processor behavior:\n\n- real JS/TS diagnostics inside Pug expression sites such as `#{...}`, `${...}`, `tag= ...`, attribute expressions, and inline handler/function bodies are mapped back to the original Pug source\n- formatting diagnostics for those embedded expression sites are linted against source-faithful JS wrappers rather than only against generated JSX\n- autofixes and suggestions for those embedded expression sites are mapped back to the original Pug source\n- diagnostics that originate only from synthetic generated helper code are filtered out\n- the processor formats against the project's own `@stylistic` package when available so generated JSX converges to the same style engine the outer ESLint run uses\n\nCurrent limitation:\n\n- multiline unbuffered `- ...` statements that are authored across several Pug lines do not yet get the same source-faithful formatting-diagnostic surface as embedded expression sites\n- diagnostics that arise only on the generated JSX surface of a transformed Pug region still do not map autofixes back; those remain report-only unless they come from an embedded source-faithful JS site\n- the internal formatter still relies on deprecated `@stylistic/jsx-indent` / `@stylistic/jsx-indent-props` compatibility rules, so some dependency graphs may emit a one-time deprecation warning during an ESLint run\n\n## VS Code Settings\n\n- `pugReact.enabled`\n- `pugReact.diagnostics.enabled`\n- `pugReact.tagFunction`\n- `pugReact.requirePugImport`: `boolean` (default `false`)\n- `pugReact.injectCssxjsTypes`: `never | auto | force`\n- `pugReact.classShorthandProperty`: `auto | className | class | styleName`\n- `pugReact.classShorthandMerge`: `auto | concatenate | classnames`\n- `pugReact.componentPathFromUppercaseClassShorthand`: `boolean` (default `true`)\n\nImport handling:\n\n- used `pug` imports are removed automatically from transformed output and shadow documents\n- when `requirePugImport` is enabled, using the configured tag without an explicit import is treated as an error\n- when a terminal `style` block is used, `pug` must be imported so the matching `css`/`styl`/`sass`/`scss` helper can be resolved from the same module\n\nClass shorthand behavior:\n\n- default auto: `className` + string concatenation\n- auto with `startupjs`/`cssxjs` marker: `styleName` + classnames-style array merge\n\n## Development\n\n```bash\nnpm ci\nnpm run typecheck\nnpm run build\nnpm run test:core\nnpm run test:ts-plugin\nnpm run test:vscode\nnpm test\n```\n\nIf you are working in an environment with `NODE_ENV=production`, install dev dependencies explicitly:\n\n```bash\nnpm ci --include=dev\n```\n\nUseful:\n\n```bash\nnpm run test:vscode:example:screenshots\nnpm run vscode:fresh:example\nnpm run check:pug:example\nnpx @react-pug/check-types .\nnpx @react-pug/check-types src/App.tsx src/Button.tsx\n```\n\nPug-aware CI type check for a target project (without VS Code UI):\n\n```bash\nnpx @react-pug/check-types \u003cproject-dir\u003e\n```\n\nIf you are using StartupJS, the same checker can be exposed as:\n\n```bash\nnpx startupjs check\n```\n\n## How It Works (High Level)\n\n1. `@react-pug/react-pug-core` finds tagged templates and compiles Pug regions.\n2. For editor tooling, the TS plugin builds a shadow document and remaps LS results.\n3. For build/lint tooling, compiler adapters transform source and remap diagnostics to original Pug ranges.\n\n## Embedded Style Blocks\n\nTerminal `style` blocks can be embedded at the end of a `pug` template:\n\n```pug\npug`\n  .title Hello\n  style(lang='styl')\n    .title\n      color red\n`\n```\n\nBehavior:\n\n- `style` defaults to `css`\n- supported langs: `css`, `styl`, `sass`, `scss`\n- the `style` block must be the last top-level node in the template\n- its content is moved to the top of the immediate enclosing scope as `css```, `styl```, `sass``` or `scss``` and keeps `${...}` interpolations intact\n- target scope selection:\n  - nearest enclosing block scope\n  - expression-bodied arrow functions are rewritten so the helper call can be inserted before the returned expression\n  - single-line `if` / `else` / loop statement bodies are normalized into blocks when needed so the helper call can be inserted before the original statement\n  - `Program` scope inserts right after the last import or directive\n- the helper import is added from the same module as the file's `pug` import unless it already exists\n\n## Supported\n\n- tags/components\n- attrs and spread attrs\n- class/id shorthand\n- interpolation: `#{}`, `!{}`, and `${}` (including nested `pug`)\n- line expressions: `tag= expression`\n- control flow: `if`, `else if`, `else`, `each`, `while`, `case/when`\n- unbuffered code: `- ...`\n- text nodes and `|` piped text\n- terminal `style` blocks with embedded CSS/SCSS editor support, plus Stylus/Sass when the corresponding VS Code language extension is installed\n\n## Known Limitations\n\n- VS Code extension currently targets desktop extension host (not web extension host).\n- During heavily malformed in-progress edits, temporary mapping can be approximate until syntax stabilizes.\n- Babel `sourceMaps: 'basic'` is compatibility-first and does not preserve fine-grained mappings within a transformed Pug region. Surrounding non-Pug JS/TS code keeps normal Babel mappings. Use `sourceMaps: 'detailed'` when you need granular Babel source maps inside Pug.\n- Embedded Stylus editor IntelliSense depends on the external VS Code Stylus extension being installed.\n- Embedded Sass editor IntelliSense/highlighting depends on the VS Code extension `Syler.sass-indented` being installed. Built-in VS Code CSS support handles `css` and `scss`, but not indented `sass`.\n\n## Repo Docs For Contributors / Agents\n\nIf you are working on the repo itself and are cold-starting on the implementation, read these first:\n\n- [architecture.md](architecture.md): current package boundaries, transform/mapping model, ESLint/TS/VS Code architecture\n- [plan.md](plan.md): current status, known limitations, validation expectations, and recommended next work\n- [performance.md](performance.md): where cost actually lives and what is or is not worth optimizing\n\nThis is mainly for contributors and agents doing actual improvements to the repo, not for normal users of the packages. Those docs capture the current architecture, the known contract boundaries, and the operational gotchas that are easy to miss if you jump straight into the code.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstartupjs%2Freact-pug","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstartupjs%2Freact-pug","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstartupjs%2Freact-pug/lists"}