OpenShock Frontend

master
develop

This is the frontend for the OpenShock project that interfaces with the OpenShock API.

Technologies

Available Commands

• pnpm i - Install dependencies
• pnpm run dev - Start the development server
• pnpm run build - Build the project
• pnpm run preview - Preview the built project
• pnpm run regen-api - Generate the API client

Setup

To clone the project you may need to rewrite git HTTPS urls to SSH for the submodule checkout to work on your machine. You can do this with git config --global url."git@github.com:".insteadOf "https://github.com/"

To get started with development, you will need to have Node.js and pnpm installed. We recommend using a node version manager of your choice.

Install dependencies and build project

With Node.js installed, you can run the following commands to get started:

pnpm i
pnpm run build

Running locally

Running the frontend locally is as simple as this:

pnpm run dev

Hosts redirect

If you do not have a hosts file config for your domain and try to run the project you will get the following example message:

Please ensure that local.openshock.app resolves to 127.0.0.1 in your hosts file

On macOS and Linux, you can do this by running the following command:
echo "127.0.0.1 local.openshock.app" | sudo tee -a /etc/hosts

On Windows, you can do this by running the following command in PowerShell as an administrator:
Add-Content -Path "C:\Windows\System32\drivers\etc\hosts" -Value "127.0.0.1 local.openshock.app"

Then restart your development server

This action is required because of cookie policy, once you have done this you should be set!

Try closing and re-opening your development environment or console to refresh its cached system config.

📂 Project Structure

.changestes/   # Versioning and changelog automation
.github/       # GitHub workflows
e2e/           # End-to-end tests (Playwright)
patches/       # Manual patches to npm dependencies (used with patch-package)
static/        # Public assets served directly (e.g., images, icons)
src/           # Application source code
├── lib/       # Shared modules and utilities
│   ├── api/               # API clients
│   │   └── internal/      # Autogenerated API client (DO NOT EDIT MANUALLY)
│   ├── components/        # UI components
│   │   ├── metadata/      # Meta helpers for SEO and accessibility
│   │   ├── svg/           # Customizable SVG icons
│   │   └── ui/            # Shadcn UI components (Do not add custom components here)
│   ├── constants/         # Global constants
│   ├── errorhandling/     # Error handling utilities
│   ├── hooks/             # Svelte hooks
│   ├── inputvalidation/   # Input validators for usage with input fields
│   ├── signalr/           # SignalR real-time communication logic
│   ├── stores/            # Svelte stores for global state management
│   ├── typeguards/        # Type guard helpers for runtime type checking
│   ├── types/             # Global TypeScript types
│   └── utils/             # General utilities
├── params/                # SvelteKit route parameter matchers
├── routes/                # Application routes (file-based routing)
│   ├── (app)/             # Protected routes (everything under this folder requires authentication)
│   │   └── +layout.svelte # Authentication boundary and layout
│   ├── +error.svelte      # Global error fallback
│   └── +layout.svelte     # Root layout and entrypoint
├── app.css    # Global styles
├── app.d.ts   # Global type declarations
└── app.html   # HTML root template
└── error.html # Fallback HTML error page (for critical errors)

Configuration files

📦 Node & pnpm

• .npmrc — npm configuration.
• .nvmrc — Node.js version manager file.
• package.json, pnpm-lock.yaml — Project dependencies and lockfile.

⚙️ Configuration & Tooling

• .editorconfig — Editor formatting consistency across IDEs.
• .prettierrc, .prettierignore — Code formatting rules (Prettier).
• eslint.config.js — Linting setup (ESLint).
• tsconfig.json — TypeScript compiler configuration.
• vite.config.ts — Vite bundler config.
• svelte.config.js — SvelteKit configuration.
• components.json — Component metadata for shadcn.
• playwright.config.ts — End-to-end testing configuration (Playwright).

🌐 Environment Variables

This project leverages Vite's environment handling, following SvelteKit's default convention: publicly accessible variables must be prefixed with PUBLIC_, while non-prefixed variables remain server-side and secure.

Environment variables are loaded in this priority:

1. System environment variables
2. .env.{mode}.local
3. .env.{mode}
4. .env.local
5. .env

With this import order, system environment variables will override any .env files, making sure CI/CD and production environments can set their own variables without needing to modify the codebase.

Any file ending with .local are meant for setting local development variables and should not be committed to Git.

🐳 Containerization

• Dockerfile — Container definition for deployment or local dev.
• .dockerignore — Files to exclude from Docker build context.

Selfhosting

A guide to selfhost can be found on the wiki. Alternatively you can deploy it to cloudflare workers using wrangler (or forking it).

Support

You can support the openshock dev team here: Sponsor OpenShock

For self hosting support consider supporting us via the link above.