OpenNoodl/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-009-template-system-refactoring/README.md

TASK-009: Template System Refactoring

Status: 📋 Planned
Priority: Medium
Complexity: Medium
Estimated Effort: 2-3 days

Context

The current project template system has several issues:

• Path resolution fails in webpack bundles (__dirname doesn't work correctly)
• No proper template provider for local/bundled templates
• Template loading depends on external URLs or fragile file paths
• New projects currently use a programmatic workaround (minimal project.json generation)

Current Temporary Solution

As of January 2026, new projects are created programmatically in LocalProjectsModel.ts:

// Create a minimal Hello World project programmatically
const minimalProject = {
  name: name,
  components: [
    /* basic App component with Text node */
  ],
  settings: {},
  metadata: {
    /* ... */
  }
};

This works but is not ideal for:

• Creating rich starter templates
• Allowing custom/community templates
• Supporting multiple bundled templates (e.g., "Hello World", "Dashboard", "E-commerce")

Goals

Primary Goals

1. Robust Template Loading: Support templates in both development and production
2. Local Templates: Bundle templates with the editor that work reliably
3. Template Gallery: Support multiple built-in templates
4. Custom Templates: Allow users to create and share templates

Secondary Goals

1. Template versioning and migration
2. Template metadata (screenshots, descriptions, categories)
3. Template validation before project creation
4. Template marketplace integration (future)

Proposed Architecture

1. Template Storage Options

Option A: Embedded Templates (Recommended)

• Store templates as JSON structures in TypeScript files
• Import and use directly (no file I/O)
• Bundle with webpack automatically
• Example:

export const helloWorldTemplate: ProjectTemplate = {
  name: 'Hello World',
  components: [
    /* ... */
  ],
  settings: {
    /* ... */
  }
};

Option B: Asset-Based Templates

• Store templates in packages/noodl-editor/assets/templates/
• Copy to build output during webpack build
• Use proper asset loading (webpack copy plugin)
• Access via runtime asset path resolution

Option C: Hybrid Approach

• Small templates: embedded in code
• Large templates: assets with proper bundling
• Choose based on template size/complexity

2. Template Provider Architecture

interface ProjectTemplate {
  id: string;
  name: string;
  description: string;
  category: string;
  version: string;
  thumbnail?: string;

  // Template content
  components: ComponentDefinition[];
  settings: ProjectSettings;
  metadata?: Record<string, unknown>;
}

interface TemplateProvider {
  name: string;
  list(): Promise<ProjectTemplate[]>;
  get(id: string): Promise<ProjectTemplate>;
  canHandle(id: string): boolean;
}

class EmbeddedTemplateProvider implements TemplateProvider {
  // Returns templates bundled with the editor
}

class RemoteTemplateProvider implements TemplateProvider {
  // Fetches templates from Noodl docs/CDN
}

class LocalFileTemplateProvider implements TemplateProvider {
  // Loads templates from user's filesystem (for custom templates)
}

3. Template Manager

class TemplateManager {
  private providers: TemplateProvider[];

  async listTemplates(filter?: TemplateFilter): Promise<ProjectTemplate[]> {
    // Aggregates from all providers
  }

  async getTemplate(id: string): Promise<ProjectTemplate> {
    // Finds the right provider and fetches template
  }

  async createProjectFromTemplate(template: ProjectTemplate, projectPath: string, projectName: string): Promise<void> {
    // Creates project structure from template
  }
}

Implementation Plan

Phase 1: Foundation (1 day)

• Define ProjectTemplate interface
• Create TemplateProvider interface
• Implement EmbeddedTemplateProvider
• Create TemplateManager class

Phase 2: Built-in Templates (1 day)

• Convert current Hello World to embedded template
• Add "Blank" template (truly empty)
• Add "Dashboard" template (with nav + pages)
• Add template metadata and thumbnails

Phase 3: Integration (0.5 days)

• Update LocalProjectsModel to use TemplateManager
• Remove programmatic project creation workaround
• Update project creation UI to show template gallery
• Add template preview/selection dialog

Phase 4: Advanced Features (0.5 days)

• Implement template validation
• Add template export functionality (for users to create templates)
• Support template variables/parameters
• Add template upgrade/migration system

Files to Modify

New Files

• packages/noodl-editor/src/editor/src/models/template/ProjectTemplate.ts
• packages/noodl-editor/src/editor/src/models/template/TemplateProvider.ts
• packages/noodl-editor/src/editor/src/models/template/TemplateManager.ts
• packages/noodl-editor/src/editor/src/models/template/providers/EmbeddedTemplateProvider.ts
• packages/noodl-editor/src/editor/src/models/template/templates/ (folder for template definitions)
  • hello-world.ts
  • blank.ts
  • dashboard.ts

Existing Files to Update

• packages/noodl-editor/src/editor/src/utils/LocalProjectsModel.ts
  • Replace programmatic project creation with template system
• packages/noodl-editor/src/editor/src/pages/ProjectsPage/ProjectsPage.tsx
  • Add template selection UI
• packages/noodl-editor/src/editor/src/utils/forge/ (might be refactored or replaced)

Testing Strategy

Unit Tests

• Template provider loading
• Template validation
• Project creation from template
• Template merging/variables

Integration Tests

• Create project from each bundled template
• Verify all templates load correctly
• Test template provider fallback

Manual Tests

• Create projects from templates in dev mode
• Create projects from templates in production build
• Verify all components and nodes are created correctly
• Test custom template import/export

Success Criteria

• New projects can be created from bundled templates reliably
• Templates work identically in dev and production
• At least 3 high-quality bundled templates available
• Template system is extensible for future templates
• No file path resolution issues
• User can export their project as a template
• Documentation for creating custom templates

Future Enhancements

• Template Marketplace: Browse and download community templates
• Template Packages: Include external dependencies/modules
• Template Generator: AI-powered template creation
• Template Forking: Modify and save as new template
• Template Versioning: Update templates without breaking existing projects

References

• Current implementation: packages/noodl-editor/src/editor/src/utils/LocalProjectsModel.ts (lines 295-360)
• Failed attempt: packages/noodl-editor/src/editor/src/utils/forge/template/providers/local-template-provider.ts
• Template registry: packages/noodl-editor/src/editor/src/utils/forge/index.ts

Related Tasks

• None yet (this is the first comprehensive template system task)

---

Created: January 8, 2026
Last Updated: January 8, 2026
Assignee: TBD