<PROJECT_NAME>

<PROJECT_NAME> is a Svelte-based application template intended as a reusable starting point for web, desktop, and mobile applications.

It provides a standardized development environment, build workflow, containerization setup, versioning strategy, and optional Tauri integration.

---

Purpose

This repository serves as a base template for new projects.

Its goal is to provide a consistent project structure and development workflow with:

• Svelte / SvelteKit frontend development
• Vite-based development and build tooling
• Reproducible Nix development environments
• Containerized deployment using Podman
• Semantic version generation using GitVersion
• Optional Tauri support for desktop and mobile applications
• Shared Makefile commands for development, testing, building, and deployment

When creating a new project from this template, replace the project-specific placeholders and remove any functionality that is not required.

---

Technology Stack

Frontend

• Svelte 5 Component-based frontend framework.

• SvelteKit Application framework providing routing, layouts, build integration, and application structure.

• Vite Development server and production build system used by SvelteKit.

• TypeScript Used for typed application logic and configuration.

Desktop & Mobile

• Tauri 2 Optional native application wrapper for building desktop, Android, and iOS applications.

• Rust / Cargo Required by Tauri for native application components.

Development Environment

• Nix / Nix Flakes Provides reproducible development and build environments.

The project may provide separate Nix environments for:

• server / CI builds
• local UI development
• Android / Tauri development

Containerization

• Podman Used to build and run OCI-compatible container images.

The project can therefore be deployed using Podman or another OCI-compatible container runtime.

Versioning

• GitVersion Automatically derives semantic versions from the Git history and branch structure.

Generated versions are used for:

• application version metadata
• npm package versions
• container image tags
• release channels

Build Automation

• GNU Make Provides common commands for development, testing, versioning, container builds, and Tauri targets.

---

Project Configuration

When creating a new repository from this template, update the project-specific configuration.

At minimum, check:

README.md
Makefile
package.json
src/
static/
svelte.config.js
vite.config.ts

The Makefile contains values such as:

APP_NAME ?= <PROJECT_NAME>
ORGANISATION ?= <ORGANISATION>
SERVER_ADDRESS ?= <REGISTRY_ADDRESS>

These should be adjusted for the new project.

---

Getting Started

1. Enter the Development Environment

The project may provide multiple Nix development environments.

Server / Build Environment

For building, CI, containerization, and general development:

nix develop

UI / Tauri Development Environment

For local Tauri and Android development:

nix develop .#ui

The exact environments available depend on the project's flake.nix.

---

2. Install Dependencies

Install the frontend dependencies:

npm install

---

3. Run the Development Server

Start the local development server:

npm run dev

or:

make dev

To expose the development server to the local network:

npm run dev -- --host

or use:

make demo

---

Building

Create a production web build:

npm run build

or:

make build

Preview the generated production build:

npm run preview

Depending on the deployment target, the appropriate SvelteKit adapter must be configured.

---

Testing & Checks

Individual targets are available for:

make lint
make unit-tests
make integration-tests
make tests

The template may initially contain placeholder implementations for tests or linting.

Replace these targets as the project introduces the respective tools.

---

Versioning

The template uses GitVersion to automatically calculate application versions.

Generate the current version:

make version

This generates:

.version.env

with values such as:

APP_NAME=<PROJECT_NAME>
SERVER_ADDRESS=<REGISTRY_ADDRESS>
ORGANISATION=<ORGANISATION>
CHANNEL_TAG=alpha
VERSION=1.2.3
FULL_VERSION=1.2.3+4

The generated semantic version is also applied to package.json.

Release Channels

The default branch mapping is:

Branch	Channel Tag
main	latest
develop	beta
other branches	alpha

This behavior can be changed in the Makefile and the Gitversion config.

---

Container Build

Build the application as a container:

make podman-build

The generated image is tagged using both:

• the semantic application version
• the current release channel

Example:

registry.example.com/example/my-app:1.4.2
registry.example.com/example/my-app:beta

Run the generated image locally:

make podman-run

The application is typically exposed on:

http://localhost:8080

The exact internal and external ports depend on the project configuration.

---

Android & iOS

If the project uses Tauri, mobile development targets are provided.

Android

Run the application on Android:

npm run tauri android dev

or:

make android

Build an Android App Bundle:

make android-build

Open the Android project in Android Studio:

npm run tauri android dev --open

iOS

iOS development requires macOS and Xcode.

Run the application:

npm run tauri ios dev

or:

make ios

Build the iOS application:

make ios-build

Open the native project in Xcode:

npm run tauri ios dev --open

Projects that do not require native applications can remove the Tauri configuration and related Make targets.

---

Makefile Commands

Common project commands include:

make dev
make demo

make lint
make unit-tests
make integration-tests
make tests

make version
make build

make podman-build
make podman-run

make android
make android-build

make ios
make ios-build

---

Project Structure

A project created from this template may look similar to:

.
├── src/
├── static/
├── src-tauri/
├── Makefile
├── Dockerfile
├── package.json
├── flake.nix
├── flake.lock
├── svelte.config.js
├── tsconfig.json
└── vite.config.ts

Not every project requires every directory.

For example:

• src-tauri/ can be removed for web-only projects.
• container configuration can be removed if the application is not deployed as an OCI image.
• additional backend directories can be introduced for larger projects.

---

Creating a New Project from this Template

After creating a repository from this template:

1. Rename the project in README.md.
2. Update project metadata in package.json.
3. Update APP_NAME, ORGANISATION, and SERVER_ADDRESS in the Makefile.
4. Update application titles, icons, and metadata.
5. Adjust the SvelteKit adapter for the intended deployment target.
6. Remove unused Tauri, container, or Nix functionality.
7. Configure testing and linting for the project.
8. Update CI/CD workflows and registry addresses.
9. Define the project's license and contribution policy.

---

Contributing

<CONTRIBUTION_POLICY>

For example:

This project is currently not open for public contributions.

Internal development only.

Replace this section according to the requirements of the project.

---

License

<LICENSE_INFORMATION>

Define the project's license before public distribution.

If no license is defined, the repository should not be assumed to grant permission for reuse or redistribution.