docs-v2/.github/instructions/assets.instructions.md

applyTo
assets/js/**/*.js, assets/js/**/*.ts

JavaScript and TypeScript Guidelines

TypeScript Configuration

Project uses TypeScript with ES2020 target:

• Config: tsconfig.json
• Source: assets/js/**/*.ts
• Output: dist/
• Build: yarn build:ts
• Watch: yarn build:ts:watch

Component Pattern

1. Add data-component attribute to HTML element:

   <div data-component="my-component"></div>
   

2. Create component module in assets/js/components/:

   // assets/js/components/my-component.ts
   export function initMyComponent(element: HTMLElement): void {
     // Component logic
   }
   

3. Register in assets/js/main.js:

   import { initMyComponent } from './components/my-component';
   
   registerComponent('my-component', initMyComponent);
   

Debugging

Method 1: Chrome DevTools with Source Maps

1. VS Code: Run > Start Debugging
2. Select "Debug Docs (source maps)"
3. Set breakpoints in assets/js/ns-hugo-imp: namespace

Method 2: Debug Helpers

import { debugLog, debugBreak, debugInspect } from './utils/debug-helpers';

const data = debugInspect(someData, 'Data');
debugLog('Processing data', 'myFunction');
debugBreak(); // Breakpoint

Start with: yarn hugo server Debug with: VS Code "Debug JS (debug-helpers)" configuration

Remove debug statements before committing.

Type Safety

• Use strict TypeScript mode
• Add type annotations for parameters and returns
• Use interfaces for complex objects
• Enable checkJs: false for gradual migration

For complete JavaScript documentation, see DOCS-CONTRIBUTING.md.