Developing Augmented Reality (AR) Applications with TypeScript

---
description: Enforce TypeScript best practices for developing Augmented Reality (AR) applications using WebXR APIs.
globs: ["**/*.ts", "**/*.tsx"]
tags: [TypeScript, AR, WebXR, Best Practices]
priority: 1
version: 1.0.0
---

# Developing Augmented Reality (AR) Applications with TypeScript

## Context
- Applicable when developing AR applications using TypeScript and WebXR APIs.
- Ensures code quality, maintainability, and scalability in AR projects.

## Requirements

- **Strict Type Checking**: Enable strict type checking in `tsconfig.json` to catch potential errors early.
  ```json
  {
    "compilerOptions": {
      "strict": true
    }
  }
  ```

- **Explicit Type Annotations**: Define explicit types for variables, function parameters, and return types to enhance code clarity and maintainability.
  ```typescript
  interface ARObject {
    id: string;
    position: [number, number, number];
    rotation: [number, number, number];
  }

  function createARObject(object: ARObject): void {
    // Implementation
  }
  ```

- **Avoid `any` Type**: Refrain from using the `any` type to maintain type safety. Use `unknown` if the type is truly unknown and perform type assertions as needed.
  ```typescript
  let data: unknown;
  if (typeof data === 'string') {
    // Handle string case
  }
  ```

- **Modular Code Structure**: Organize code into modules to promote reusability and maintainability.
  ```typescript
  // ar-utils.ts
  export function initializeARSession(): void {
    // Implementation
  }

  // main.ts
  import { initializeARSession } from './ar-utils';
  initializeARSession();
  ```

- **Consistent Naming Conventions**: Use camelCase for variables and functions, PascalCase for classes and interfaces, and UPPERCASE for constants.
  ```typescript
  const MAX_OBJECTS = 100;

  class ARScene {
    // Implementation
  }

  function renderScene(): void {
    // Implementation
  }
  ```

- **Error Handling**: Implement proper error handling mechanisms to manage exceptions and errors gracefully.
  ```typescript
  try {
    // AR session initialization
  } catch (error) {
    console.error('Failed to initialize AR session:', error);
  }
  ```

- **Documentation**: Use JSDoc comments to document functions, classes, and interfaces for better code understanding.
  ```typescript
  /**
   * Initializes the AR session.
   * @returns {Promise<void>} A promise that resolves when the session is initialized.
   */
  async function initializeARSession(): Promise<void> {
    // Implementation
  }
  ```

- **Testing**: Write unit tests for all new components and utilities to ensure code reliability.
  ```typescript
  // ar-utils.test.ts
  import { initializeARSession } from './ar-utils';

  test('initializeARSession initializes without errors', () => {
    expect(() => initializeARSession()).not.toThrow();
  });
  ```

## Examples

<example>
// Good Example: Explicit type annotations and modular structure
import { initializeARSession } from './ar-utils';

async function startAR(): Promise<void> {
  try {
    await initializeARSession();
    console.log('AR session started successfully.');
  } catch (error) {
    console.error('Error starting AR session:', error);
  }
}

startAR();
</example>

<example type="invalid">
// Bad Example: Using 'any' type and lack of error handling
function startAR(): any {
  // AR session initialization without error handling
}
</example>