Skip to main content

​
Prerequisites

Before you begin development, ensure you have the following installed:
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.
Ensure Git is installed for version control:
git --version

​
Development Installation

​
1. Fork and Clone

1

Fork the repository

Fork the Sora Digital Photo Frame repository on GitHub.
2

Clone your fork

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

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

  1. Copy the example environment file:
cp .env.example .env
  1. 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
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

1

Start the development server

npm run dev
This starts the server with hot reloading and development logging enabled.
2

Access the application

Open your browser to:
3

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

​
Development Guidelines

​
Code Style

  • 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
}
  • Follow Material Design principles
  • Use CSS custom properties for theming
  • Mobile-first responsive design
  • BEM naming convention for CSS classes

​
Git Workflow

1

Create feature branch

git checkout -b feature/your-feature-name
2

Make your changes

Develop your feature with frequent commits:
git add .
git commit -m "feat: add new slideshow transition effect"
3

Keep updated

Regularly sync with upstream:
git fetch upstream
git rebase upstream/main
4

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

Use Node.js debugger or VS Code:
# Start with Node.js debugger
node --inspect src/server.js

# Or use npm script
npm run debug
  • 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.