react-pug

Pug IntelliSense for React inside pug\...`` tagged templates in VS Code.

You get JSX-like editor features inside Pug regions:

• completions
• hover
• go-to-definition
• rename/references
• diagnostics/code actions
• syntax highlighting

Install

Option 1: Install from VSIX (from this repo)

npm ci
npm run package:vsix
code --install-extension packages/vscode-react-pug-tsx/*.vsix

Option 2: Install from Marketplace

If published in your environment, install extension id:

code --install-extension startupjs.vscode-react-pug-tsx

Quick Setup

Extension activates automatically for:

• TypeScript / TSX
• JavaScript / JSX

No tsconfig.json plugin setup or extra npm install is required when using this VS Code extension.

Usage

import { Button } from './Button'

const view = pug`
  .app
    Button(onClick=handleClick label="Click")
    if show
      p Hello #{user.name}
`

Command palette command:

• Pug React: Show Shadow TSX (opens generated shadow TSX)

Main settings:

• pugReact.enabled (default true)
• pugReact.diagnostics.enabled (default true)
• pugReact.tagFunction (default "pug")
• pugReact.injectCssxjsTypes ("never" | "auto" | "force", default "auto")

Requirements

• VS Code ^1.85.0
• TypeScript project using a runtime/build transform such as:
  • babel-plugin-transform-react-pug
  • @startupjs/babel-plugin-transform-react-pug

This extension provides editor tooling only. It does not perform runtime/build transforms.

Development

npm ci
npm run typecheck
npm run build
npm run test:unit
npm run test:vscode
npm test

Useful extras:

npm run test:vscode:example:screenshots
npm run vscode:fresh:example
npm run check:pug:example

Pug-aware CI type check command (without launching VS Code):

node scripts/check-pug-types.mjs <project-dir>

Architecture

For the detailed technical design, data flow, mappings, plugin interception strategy, and test architecture, see:

• architecture.md

How It Works (High Level)

1. The TypeScript plugin finds pug\...`` regions in your file.
2. Each Pug region is compiled into a shadow TSX representation.
3. TypeScript language service runs against that shadow text.
4. Results (completions, diagnostics, definitions, etc.) are mapped back to original Pug positions.

This keeps native TS/VS Code behavior while giving JSX-like tooling inside Pug templates.

Supported

High-level supported Pug features:

• tags/components
• attributes and spread attributes
• class/id shorthand
• interpolation (#{} / !{} / ${})
• line expressions (tag= expression)
• conditionals (if / else if / else)
• loops (each, while)
• code lines (- ...)
• text nodes and piped text (|)

Known Limitations

• This extension provides editor tooling only (not runtime/build-time transform).
• In heavily malformed in-progress edits, temporary IntelliSense mapping may be approximate until syntax stabilizes.