Setup

Prerequisites

Before you begin development, ensure you have the following installed:

Node.js 18.0+

Install Node.js version 18.0 or higher:

# Check your current version
node --version

# Should return v18.0.0 or higher

Download from nodejs.org if you need to upgrade.

Git

Ensure Git is installed for version control:

git --version

Development Installation

1. Fork and Clone

Fork the repository

Fork the Sora Digital Photo Frame repository on GitHub.

Clone your fork

git clone https://github.com/YOUR_USERNAME/sora-digital-photo-frame.git
cd sora-digital-photo-frame

Add upstream remote

git remote add upstream https://github.com/Sorbh/sora-digital-photo-frame.git

2. Install Dependencies

Install all project dependencies:

npm install

This will install both runtime and development dependencies needed for the project.

3. Environment Configuration

Development environment

Copy the example environment file:

cp .env.example .env

Configure for development:

# Server Configuration
PORT=3000
NODE_ENV=development

# Authentication (for development)
ADMIN_PASSWORD=dev123

# Upload Configuration
MAX_FILE_SIZE=10485760
UPLOAD_DIR=uploads

# Image Processing
IMAGE_QUALITY=85
MAX_RESOLUTION_WIDTH=1920
MAX_RESOLUTION_HEIGHT=1080

# Development flags
DEBUG=true
LOG_LEVEL=debug

Test photos directory

Create a test photos directory for development:

mkdir uploads
mkdir uploads/test-photos

Add some test images to verify your setup works correctly.

Development Workflow

Running in Development Mode

Start the development server

npm run dev

This starts the server with hot reloading and development logging enabled.

Access the application

Open your browser to:

Main app: http://localhost:3000
Admin panel: http://localhost:3000/admin

Test photo upload

Navigate to the admin panel and test uploading photos to ensure everything works.

Available Scripts

npm run dev          # Start with hot reloading
npm run dev:debug    # Start with debug logging

npm start           # Production server
npm run build       # Build for production

npm test           # Run test suite
npm run test:watch # Run tests in watch mode
npm run test:coverage # Run with coverage report

npm run lint       # Run ESLint
npm run lint:fix   # Fix auto-fixable issues
npm run format     # Format code with Prettier

Development Guidelines

Code Style

JavaScript/Node.js

Use ES6+ features and async/await
Follow ESLint configuration
Use meaningful variable and function names
Add JSDoc comments for functions

/**
 * Resizes an image to specified dimensions
 * @param {string} inputPath - Path to input image
 * @param {Object} options - Resize options
 * @returns {Promise<string>} Path to resized image
 */
async function resizeImage(inputPath, options) {
  // Implementation
}

CSS/Styling

Follow Material Design principles
Use CSS custom properties for theming
Mobile-first responsive design
BEM naming convention for CSS classes

Git Workflow

Create feature branch

git checkout -b feature/your-feature-name

Make your changes

Develop your feature with frequent commits:

git add .
git commit -m "feat: add new slideshow transition effect"

Keep updated

Regularly sync with upstream:

git fetch upstream
git rebase upstream/main

Push and create PR

git push origin feature/your-feature-name

Then create a Pull Request on GitHub.

Testing

Running Tests

# Run all tests
npm test

# Run tests in watch mode during development
npm run test:watch

# Run with coverage report
npm run test:coverage

Writing Tests

Create tests in the tests/ directory:

// tests/api/photos.test.js
const request = require('supertest');
const app = require('../../src/server');

describe('Photos API', () => {
  test('GET /api/photos returns photo list', async () => {
    const response = await request(app)
      .get('/api/photos')
      .expect(200);
      
    expect(response.body).toHaveProperty('photos');
  });
});

Debugging

Server-side debugging

Use Node.js debugger or VS Code:

# Start with Node.js debugger
node --inspect src/server.js

# Or use npm script
npm run debug

Client-side debugging

Use browser Developer Tools
Check console for JavaScript errors
Use Network tab to inspect API calls
Test responsive design in device emulation

Common Development Tasks

Add API Endpoint

Create new routes in src/routes/ and register them in the main server file.

Modify UI

Update HTML templates and CSS in the public/ directory.

Add Configuration

Add new environment variables to .env.example and document them.

Optimize Images

Modify image processing utilities in src/utils/imageProcessor.js.

Performance Considerations

Image Processing: Use efficient libraries like Sharp for image manipulation
Caching: Implement proper caching strategies for processed images
Memory Usage: Monitor memory usage with large image collections
Network: Optimize image delivery with appropriate compression

Need Help?

Stuck on something? Check the contributing guidelines or open an issue on GitHub for help from the community.

Getting Started

Development

Deployment

Prerequisites

Development Installation

1. Fork and Clone

2. Install Dependencies

3. Environment Configuration

Development Workflow

Running in Development Mode

Available Scripts

Development Guidelines

Code Style

Git Workflow

Testing

Running Tests

Writing Tests

Debugging

Common Development Tasks

Add API Endpoint

Modify UI

Add Configuration

Optimize Images

Performance Considerations

Need Help?

​Prerequisites

​Development Installation

​1. Fork and Clone

​2. Install Dependencies

​3. Environment Configuration

​Development Workflow

​Running in Development Mode

​Available Scripts

​Development Guidelines

​Code Style

​Git Workflow

​Testing

​Running Tests

​Writing Tests

​Debugging

​Common Development Tasks

Add API Endpoint

Modify UI

Add Configuration

Optimize Images

​Performance Considerations

​Need Help?

Prerequisites

Development Installation

1. Fork and Clone

2. Install Dependencies

3. Environment Configuration

Development Workflow

Running in Development Mode

Available Scripts

Development Guidelines

Code Style

Git Workflow

Testing

Running Tests

Writing Tests

Debugging

Common Development Tasks

Performance Considerations

Need Help?