Aller au contenu principal

Getting Started

This guide will help you set up your development environment and start working with the TimeLock project.

Table of Contents​

  1. Prerequisites
  2. Installation
  3. Development Workflow
  4. Project Structure Overview
  5. Available Scripts
  6. Development Tools
  7. Common Tasks
  8. Troubleshooting

Prerequisites​

Before you begin, ensure you have the following installed:

Required Software​

  • Node.js (v18.19.0 or later)

    node --version  # Should be 18.19.0+

  • npm (comes with Node.js)

    npm --version   # Should be 9.0.0+

  • Git (for version control)

    git --version
  • Visual Studio Code - Excellent TypeScript and Angular support
  • Angular Language Service - VS Code extension for Angular
  • Angular DevTools - Browser extension for debugging

Browser Requirements​

  • Chrome/Edge (recommended for development)
  • Firefox (supported)
  • Safari (supported)

Installation​

1. Clone the Repository​

git clone <repository-url>
cd timelock

2. Install Dependencies​

npm install

This will install:

  • Angular framework and CLI
  • TypeScript compiler
  • Development dependencies
  • Testing frameworks (Karma, Playwright)

3. Verify Installation​

npm run ng version

You should see output similar to:

Angular CLI: 20.1.5
Node: 18.19.0
Package Manager: npm 9.8.1
OS: darwin x64

Angular: 20.1.0
... @angular/cli          20.1.5
... @angular/common       20.1.0
... @angular/compiler     20.1.0
... @angular/core         20.1.0

Development Workflow​

1. Start Development Server​

npm start
# or
ng serve
  • Opens browser to http://localhost:4200
  • Automatically reloads on file changes
  • Shows compilation errors in console and browser

2. Basic Development Cycle​

  1. Make changes to TypeScript/HTML/CSS files
  2. Save files - Angular CLI automatically recompiles
  3. Check browser - Changes appear automatically
  4. Fix errors - Check console for TypeScript/compilation errors
  5. Test functionality - Verify your changes work as expected

3. Code Quality Checks​

# TypeScript compilation check
npm run build

# Run tests
npm test

# End-to-end tests
npm run e2e

Project Structure Overview​

timelock/
├── src/                          # Source code
│   ├── app/                      # Angular application
│   │   ├── components/           # Reusable components
│   │   ├── pages/               # Route components (views)
│   │   ├── services/            # Business logic and data
│   │   ├── models/              # TypeScript interfaces
│   │   ├── app.ts               # Root component
│   │   ├── app.config.ts        # App configuration
│   │   └── app.routes.ts        # Route definitions
│   ├── assets/                  # Static files (images, icons)
│   ├── styles.css               # Global styles
│   ├── index.html               # Main HTML file
│   └── main.ts                  # Application bootstrap
├── public/                      # Public assets
├── e2e/                         # End-to-end tests
├── documentation/               # This documentation
├── angular.json                 # Angular CLI configuration
├── package.json                 # Dependencies and scripts
├── tsconfig.json               # TypeScript configuration
└── README.md                   # Basic project info

Key Directories Explained​

src/app/components/ - Reusable UI components

  • todo-item/ - Individual task display
  • todo-form/ - Task creation/editing form
  • todo-filters/ - Filter controls
  • Dialog components for various features

src/app/pages/ - Route-level components (pages)

  • projects/ - Project list view
  • project-detail/ - Individual project view
  • calendar/ - Calendar view
  • timetable/ - Time planning view
  • upcoming/ - Upcoming tasks view
  • search/ - Search functionality

src/app/services/ - Business logic and data management

  • todo.service.ts - Task management
  • project.service.ts - Project management
  • indexeddb.service.ts - Data persistence
  • tags.service.ts - Tag management

src/app/models/ - TypeScript type definitions

  • todo.model.ts - Task-related types
  • project.model.ts - Project-related types

Available Scripts​

Development Scripts​

# Start development server
npm start
npm run ng serve

# Build for production
npm run build

# Build and watch for changes
npm run watch

Testing Scripts​

# Run unit tests
npm test
npm run ng test

# Run e2e tests
npm run e2e

# Run tests with coverage
npm run ng test --code-coverage

Angular CLI Commands​

# Generate new component
npm run ng generate component my-component

# Generate new service
npm run ng generate service my-service

# Generate new interface
npm run ng generate interface my-interface

# See all available generators
npm run ng generate --help

Development Tools​

Angular DevTools​

  1. Install the browser extension:

  2. Open browser DevTools (F12)

  3. Look for "Angular" tab

  4. Explore component tree, signals, and performance

VS Code Extensions​

Install these recommended extensions:

{
  "recommendations": [
    "angular.ng-template",           // Angular Language Service
    "ms-vscode.vscode-typescript-next", // TypeScript support
    "bradlc.vscode-tailwindcss",     // CSS IntelliSense
    "esbenp.prettier-vscode",        // Code formatting
    "ms-playwright.playwright"       // E2E testing support
  ]
}

Browser Developer Tools​

Console Commands (in browser console):

// Access Angular component
ng.getComponent($0)  // $0 = selected element

// Get component context
ng.getContext($0)

// Trigger change detection
ng.applyChanges($0)

Common Tasks​

Adding a New Component​

# Generate component
npm run ng generate component components/my-component

# This creates:
# - my-component.component.ts
# - my-component.component.html  
# - my-component.component.css
# - my-component.component.spec.ts

Adding a New Service​

# Generate service
npm run ng generate service services/my-service

# This creates:
# - my-service.service.ts
# - my-service.service.spec.ts

Adding a New Route​

  1. Create the component:
npm run ng generate component pages/my-page
  1. Add route to src/app/app.routes.ts:
{
  path: 'my-page',
  loadComponent: () => import('./pages/my-page/my-page.component')
    .then(m => m.MyPageComponent)
}
  1. Add navigation link in src/app/app.ts:
<a routerLink="/my-page" routerLinkActive="active">My Page</a>

Working with Signals​

// In a service
private dataSignal = signal<Data[]>([]);
public data = this.dataSignal.asReadonly();

// In a component
export class MyComponent {
  private myService = inject(MyService);
  
  data = this.myService.data;  // Reactive data
  
  // Local component state
  isLoading = signal(false);
  
  // Computed values
  dataCount = computed(() => this.data().length);
}

Adding Dependencies​

# Add Angular Material
npm install @angular/material @angular/cdk

# Add a utility library
npm install lodash
npm install @types/lodash --save-dev

# Add to component imports
imports: [CommonModule, MatButtonModule]

Troubleshooting​

Common Issues​

1. Port 4200 already in use

# Kill process using port 4200
npx kill-port 4200

# Or use different port
ng serve --port 4201

2. Node modules issues

# Clear npm cache
npm cache clean --force

# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

3. TypeScript compilation errors

# Check TypeScript version
npm list typescript

# Restart TypeScript service in VS Code
Ctrl+Shift+P > "TypeScript: Restart TS Server"

4. Angular CLI not found

# Install Angular CLI globally
npm install -g @angular/cli

# Or use npx
npx ng serve

Performance Issues​

1. Slow compilation

  • Close unnecessary browser tabs
  • Disable browser extensions temporarily
  • Increase Node.js memory: node --max-old-space-size=8192

2. Browser memory issues

  • Clear browser cache
  • Close DevTools when not needed
  • Restart browser periodically

Getting Help​

1. Check the console

  • Browser DevTools Console (F12)
  • Terminal where ng serve is running

2. Angular documentation

3. Community resources

Next Steps​

Now that you have the development environment set up:

  1. Explore the code - Start with Code Structure
  2. Make your first change - Follow Development Guide
  3. Understand the features - Read Features Overview
  1. Run the application - npm start and explore the UI
  2. Open DevTools - Inspect components and signals
  3. Make a small change - Edit a component template
  4. Add a new feature - Follow the development guide
  5. Write tests - Learn the testing patterns

Happy coding! 🚀