Repository Structure

April 22, 2026 · View on GitHub

Comprehensive guide to the templjs monorepo organization, naming conventions, and file locations.

This document is repository reference material.

Overview

templjs is organized as a pnpm workspace monorepo using Nx for build orchestration and caching. The repository contains multiple packages, extensions, documentation, and development infrastructure.

Directory Tree

templjs/
├── .agents/                    # AI agent skills and configurations
│   ├── skills/                 # Agent skill definitions
│   └── skills-manifest.md      # Catalog of all skills
├── .changeset/                 # Changesets for versioning
│   ├── config.json             # Changeset configuration
│   └── *.md                    # Individual changesets
├── .doc-vader/                 # Backlog consumer configuration
├── .github/                    # GitHub configuration
│   ├── workflows/              # GitHub Actions workflows
│   │   ├── backlog-automation.yml # Backlog event ingestion automation
│   │   ├── ci.yml              # CI workflow (tests, lint, build)
│   │   ├── release.yml         # Release workflow (publish)
│   │   ├── codeql.yml          # Security analysis
│   │   └── benchmark.yml       # Benchmark publishing/comparison
│   ├── ISSUE_TEMPLATE/         # Issue templates
│   ├── organization-setup.md   # Repository and org admin setup
│   ├── pull_request_template.md  # PR template
│   ├── SECRETS.md              # CI/CD secret reference
│   └── copilot-instructions.md # Copilot agent instructions
├── .husky/                     # Git hooks (pre-commit, commit-msg)
├── .nx/                        # Nx cache (ignored by Git)
├── backlog/                    # Work items, evidence, and audit artifacts
│   ├── active/                 # Active work items
│   │   └── work-item-*.md
│   ├── archive/                # Completed work items
│   │   └── work-item-*.md
│   ├── records/                # Evidence records
│   │   └── record-*.md
│   └── audit/                  # Migration and reconciliation output
├── docs/                       # Documentation
│   ├── adr/                    # Architecture Decision Records
│   │   └── NNN-title.md        # Individual ADRs
│   ├── prd/                    # Product Requirements Documents
│   ├── ci-cd.md                # CI/CD infrastructure guide
│   ├── coverage-strategy.md    # Coverage policy reference
│   ├── repository-structure.md # This file
│   └── release-process.md      # Release operations guide
├── examples/                   # Example templates and usage
│   ├── README.md               # Examples overview
│   └── *.templ                 # Example template files
├── src/
│   ├── extensions/             # IDE extensions
│   │   └── vscode/             # VS Code extension
│   │       ├── src/
│   │       ├── syntaxes/       # TextMate grammars
│   │       ├── package.json    # Extension manifest
│   │       └── tsconfig.json
│   └── packages/               # Published packages
│       ├── core/               # @templjs/core
│       │   ├── src/
│       │   │   ├── lexer/      # Tokenization
│       │   │   ├── parser/     # AST generation
│       │   │   ├── renderer/   # Template rendering
│       │   │   ├── query/      # Query engine
│       │   │   └── __tests__/  # Tests (co-located)
│       │   ├── package.json
│       │   ├── tsconfig.json
│       │   ├── vitest.config.ts
│       │   └── README.md
│       ├── cli/                # @templjs/cli
│       │   ├── src/
│       │   │   ├── commands/   # CLI commands
│       │   │   ├── utils/      # Utilities
│       │   │   └── __tests__/
│       │   ├── bin/            # CLI entry point
│       │   ├── package.json
│       │   └── README.md
│       └── volar/              # @templjs/volar
│           ├── src/
│           │   ├── language-service/  # Language features
│           │   ├── utils/
│           │   └── __tests__/
│           ├── package.json
│           └── README.md
├── schemas/                    # JSON schemas
│   └── frontmatter/            # Document frontmatter schemas
│       ├── by-type/            # Schemas selected by frontmatter `type`
│       │   ├── document/
│       │   │   ├── current.json
│       │   │   ├── v1.0.0.json
│       │   │   └── latest.json
│       │   └── work-item/
│       │       ├── current.json
│       │       ├── v1.0.0.json
│       │       └── latest.json
│       ├── support/            # Shared schema building blocks
│       │   ├── base/
│       │   ├── contracts/
│       │   ├── overlays/
│       │   └── payloads/
│       └── schema-map.json     # Type -> schema routing map
│   └── work-management/        # Canonical backlog/work-management schemas
│       ├── frontmatter/
│       └── support/
├── .editorconfig               # Editor configuration
├── .eslintrc.json              # ESLint configuration
├── .gitignore                  # Git ignore rules
├── .markdownlint.yaml          # Markdown linting rules
├── .npmrc                      # npm configuration
├── .prettierrc.json            # Prettier configuration
├── codecov.yml                 # Codecov configuration
├── DEVELOPMENT.md              # Development guide
├── migration-plan.md           # Migration from Python version
├── nx.json                     # Nx configuration
├── package.json                # Root package configuration
├── pnpm-lock.yaml              # Dependency lockfile
├── pnpm-workspace.yaml         # pnpm workspace configuration
├── README.md                   # Project overview
├── templjs.code-workspace      # VS Code workspace file
└── tsconfig.base.json          # Base TypeScript configuration

Package Organization

Backlog Organization

Backlog automation uses the canonical doc-vader work-management model.

  • Work items use work-item:* identifiers and live in backlog/active/ or backlog/archive/.
  • Evidence uses record:* identifiers and lives in backlog/records/.
  • backlog/audit/ stores migration and reconciliation artifacts.
  • Use pnpm run backlog:doc-vader -- ... for backlog mutations and pnpm run lint:frontmatter to validate the results.

Core Package (@templjs/core)

Purpose: Core template engine (lexer, parser, renderer, query engine)

Key Directories:

  • src/lexer/: Tokenization (Chevrotain lexer)
  • src/parser/: Parsing (Chevrotain parser)
  • src/renderer/: Template rendering engine
  • src/query/: Query language (dot notation, JMESPath)
  • src/types/: TypeScript type definitions
  • src/__tests__/: Co-located tests

Entry Point: src/index.ts

Exports:

  • createLexer(): Lexer factory
  • createParser(): Parser factory
  • render(): Template rendering
  • query(): Query data
  • Types: Token, AST, RenderOptions

CLI Package (@templjs/cli)

Purpose: Command-line interface for template processing

Key Directories:

  • src/commands/: CLI command implementations (render, validate, init)
  • src/config/: .templjs.json config loading and schema validation
  • src/formats/: JSON/YAML/TOML/XML input parsers
  • test/: CLI integration and behavior tests

Entry Point: src/packages/cli/src/cli.ts

Path convention in this section: entry-point paths are repository-root relative (for package code, that means src/packages/<name>/...).

Commands:

  • templjs render --template <path> --input <path|->: Render template
  • templjs render --watch: Watch template/input files and re-render on changes
  • templjs validate --template <path>: Validate syntax and optional schema/input
  • templjs init --format <markdown|html|json|yaml>: Generate starter templates

Volar Plugin (@templjs/volar)

Purpose: Volar language service plugin for IDE integration

Key Directories:

  • src/language-service/: Language features (hover, completion, diagnostics)
  • src/utils/: Plugin utilities
  • src/__tests__/: Plugin tests

Entry Point: src/index.ts

Exports:

  • createVolarPlugin(): Plugin factory
  • Language service providers

VS Code Extension (vscode-templjs)

Purpose: VS Code integration via Volar

Key Directories:

  • src/: Extension source code
  • syntaxes/: TextMate grammar for syntax highlighting
  • client/: Language client
  • server/: Language server (uses Volar)

Entry Point: src/extension.ts

Features:

  • Syntax highlighting
  • Diagnostics
  • Hover information
  • Auto-completion
  • Go to definition

Documentation Organization

Architecture Decision Records (docs/adr/)

Purpose: Document significant architectural decisions

Naming Convention: NNN-title.md (e.g., 001-language-migration.md)

Format: MADR (Markdown Any Decision Records)

Sections:

  • Status: accepted, proposed, deprecated, superseded
  • Context: Problem statement
  • Decision: What was decided
  • Consequences: Implications of the decision

Index: Maintained in docs/adr/README.md

Product Requirements (docs/prd/)

Purpose: Product specifications and feature requirements

Naming Convention: feature-name.md

Format: Custom PRD template

Sections:

  • Overview
  • Goals
  • User stories
  • Technical specification
  • Success metrics

Guides (docs/)

Purpose: User and developer documentation

Key Files:

  • ci-cd.md: CI/CD infrastructure
  • repository-structure.md: This file
  • release-process.md: Release operations guide
  • DEVELOPMENT.md: Development guide (root)

Work Item Organization

Active Work Items (backlog/)

Purpose: Track in-progress and planned work

Naming Convention: NNN_description.md (e.g., 005_chevrotain_lexer.md)

Numbering:

  • Sequential numbering starting from 001
  • Zero-padded to 3 digits (001, 002, ..., 099, 100)
  • Gaps are acceptable (deleted/rejected items)

Frontmatter (see schemas/frontmatter/by-type/work-item/latest.json):

---
id: '005'
title: 'Implement Chevrotain Lexer'
status: in_progress # not_started, in_progress, testing, completed
priority: high # low, medium, high, critical
estimated_hours: 8
actual_hours: 6
started_date: 2026-02-18
completed_date: null
tags: [core, lexer, v1.0]
dependencies: ['002']
branch: feature/005-chevrotain-lexer
related_commits: [abc123, def456]
related_prs: [42]
---

Sections:

  • Goal
  • Background
  • Tasks
  • Deliverables
  • Acceptance Criteria
  • Notes

Archived Work Items (backlog/archive/)

Purpose: Historical record of completed work

When to Archive:

  • Status: completed
  • PR merged to main
  • All acceptance criteria met

Process:

# Update final status
# Edit backlog/NNN_item.md frontmatter:
# status: completed
# completed_date: 2026-02-18
# actual_hours: X

# Move to archive
mv backlog/NNN_item.md backlog/archive/

# Commit
git add backlog/archive/NNN_item.md
git commit -m "chore: archive work item NNN"

Naming Conventions

Files

TypeConventionExample
Source fileskebab-case.tstemplate-tokenizer.ts
Test files*.test.tslexer.test.ts
Config fileslowercase.jsontsconfig.json
Documentationkebab-case.mdrelease-process.md, ci-cd.md
Work itemsNNN_description.md005_chevrotain_lexer.md
ADRsNNN-title.md001-language-migration.md
Examplesdescriptive.templuser-profile.templ

Exceptions:

  • keep canonical special filenames uppercase where the toolchain expects them, such as README.md and AGENTS.md

Branches

TypeConventionExample
Stagingstagingstaging
Mainmainmain
Featurefeature/NNN-descriptionfeature/005-chevrotain-lexer
Bugfixfix/NNN-descriptionfix/042-parser-edge-case
Hotfixhotfix/NNN-descriptionhotfix/101-critical-parser
Chorechore/descriptionchore/update-deps

Release publication is tag-based, not branch-based:

  • npm package releases use vX.Y.Z
  • VS Code extension releases use vscode-vX.Y.Z

Commits

Format: Conventional Commits

<type>(<scope>): <subject>

<body>

<footer>

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • chore: Maintenance tasks
  • test: Test changes
  • refactor: Code refactoring
  • perf: Performance improvements
  • ci: CI/CD changes

Scopes:

  • core: @templjs/core changes
  • cli: @templjs/cli changes
  • volar: @templjs/volar changes
  • vscode: VS Code extension changes
  • deps: Dependency updates
  • docs: Documentation updates
  • ci: CI/CD updates

Examples:

feat(core): implement Chevrotain lexer
fix(parser): handle nested expressions correctly
docs: update README with installation steps
chore(deps): upgrade chevrotain to v11
test(lexer): add edge case for empty templates
ci: add secret scanning workflow

Pull Requests

Title Format: Same as commit message (conventional commits)

Label Conventions:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation
  • chore: Maintenance
  • breaking: Breaking change
  • needs-review: Awaiting review
  • work-in-progress: Not ready for review
  • blocked: Dependent on other work

PR Number: Auto-assigned by GitHub

Packages & Scopes

All published packages use @templjs/ scope:

  • @templjs/core: Core engine
  • @templjs/cli: CLI tool
  • @templjs/volar: Volar plugin

Non-scoped:

  • vscode-templjs: VS Code extension (marketplace requirement)

Configuration Files

Root Level

  • package.json: Root package, scripts, dev dependencies
  • pnpm-workspace.yaml: Workspace configuration
  • nx.json: Nx configuration (caching, affected commands)
  • tsconfig.base.json: Base TypeScript configuration (extended by packages)
  • .eslintrc.json: Root ESLint configuration
  • .prettierrc.json: Prettier configuration
  • .editorconfig: Editor settings (indentation, line endings)
  • .markdownlint.yaml: Markdown linting rules
  • .gitignore: Git ignore patterns
  • .npmrc: npm configuration (registry, scope)
  • codecov.yml: Codecov coverage thresholds
  • package.json toolchain fields: Canonical Node.js/pnpm pins used locally and in CI

Package Level

Each package has:

  • package.json: Package metadata, scripts, dependencies
  • tsconfig.json: TypeScript configuration (extends root)
  • vitest.config.ts: Vitest test configuration
  • README.md: Package documentation

Extension Level

VS Code extension has:

  • package.json: Extension manifest (contributes, activationEvents)
  • tsconfig.json: TypeScript configuration
  • .vscodeignore: Files to exclude from extension package

Special Directories

.nx/ (Git Ignored)

Nx computation cache. Contains cached task outputs for faster rebuilds.

Do not commit: Automatically regenerated

node_modules/ (Git Ignored)

Package dependencies installed by pnpm.

Do not commit: Installed via pnpm install

.husky/ (Committed)

Git hooks for pre-commit checks.

Commit: Ensures all contributors use same hooks

.changeset/ (Committed)

Changesets for version management. Individual changesets are committed, cache is ignored.

Commit: *.md files (changesets)
Ignore: .changeset/.cache/

Dependency Management

Dependency Types

{
  "dependencies": {}, // Runtime dependencies
  "devDependencies": {}, // Development-only dependencies
  "peerDependencies": {}, // Required by consumers
  "optionalDependencies": {} // Optional enhancements
}

Workspace Dependencies

Internal packages reference each other via workspace protocol:

{
  "dependencies": {
    "@templjs/core": "workspace:*"
  }
}

This is resolved to the actual version on publish.

Dependency Versions

  • ~: Patch updates only (~1.2.3 → 1.2.x)
  • ^: Minor updates (^1.2.3 → 1.x.x)
  • exact: No updates (1.2.3 → 1.2.3)

Policy: Use ^ for most dependencies, exact for critical dependencies

Build Outputs

.gitignore Patterns

# Build outputs
dist/
*.tsbuildinfo
.nx/cache

# Dependencies
node_modules/

# Test coverage
coverage/

# Environment
.env
.env.local

# IDE
.vscode/*
!.vscode/settings.json
!.vscode/extensions.json
.idea/

# OS
.DS_Store
Thumbs.db

Build Artifacts

  • dist/: Compiled JavaScript (ESM + CJS)
  • *.tsbuildinfo: TypeScript incremental build info
  • coverage/: Test coverage reports

Migration Context

From Python to TypeScript

This repository is the TypeScript rewrite of the original Python temple project.

Legacy Repository: /Users/macos/dev/temple/ (Python)
New Repository: /Users/macos/dev/templjs/ (TypeScript)

Migration Plan: See migration-plan.md for detailed roadmap

Coexistence: Both versions exist during migration period

Architectural Differences

AspectPython (Legacy)TypeScript (New)
ParserCustom recursive descentChevrotain (parser combinator)
LSPCustom Python LSPVolar plugin (TypeScript)
TestingpytestVitest
Buildsetup.pypnpm + Nx
PackagingPyPInpm + VS Code marketplace

Reference

  • Monorepo Structure: Defined by this file
  • Naming Conventions: This file
  • Build System: Nx (nx.json)
  • Package Manager: pnpm (pnpm-workspace.yaml)
  • Work Item Schema: schemas/frontmatter/by-type/work-item/latest.json
  • Document Schema: schemas/frontmatter/by-type/document/latest.json
  • Migration Plan: migration-plan.md