electron-shadcn

electron-shadcn is a pre-configured template for building desktop applications with Electron. It integrates several modern libraries for development, UI, and testing:

Core & DX

• Runtime: Electron 43, Vite 8
• Language & Logic: TypeScript 6, Zod 4, oRPC
• Data Fetching: React Query (TanStack)
• Formatting: Prettier, Ultracite with Biome

UI & Styling

• Framework: React 19.2 (with React Compiler enabled by default)
• Styling: Tailwind 4.3, Shadcn UI, Lucide icons
• Routing: TanStack Router (file-based)
• Internationalization: i18next
• Typography: Geist (default font)

Testing & Distribution

• Testing: Vitest, Playwright, React Testing Library
• Distribution: Electron Forge
• CI/CD: GitHub Actions (configured for Playwright tests)

To get started with the electron-shadcn template, clone the repository, install the dependencies, and run the development server. The main application entry point for the UI is located at /src/routes/index.tsx.

# 1. Clone the repository
git clone https://github.com/LuanRoger/electron-shadcn.git

# 2. Install dependencies
npm install

# 3. Run the app
npm run start

The project uses a Vite configuration to define a path alias @ which points to the ./src directory. This allows for cleaner absolute imports within the source code instead of using relative paths (e.g., import { ... } from '@/components/...').

import path from "node:path";
import { defineConfig } from "vite";

export default defineConfig({
  resolve: {
    alias: {
      "@": path.resolve(import.meta.dirname, "./src"),
    },
  },
});

The renderer process uses a Vite configuration that integrates TanStack Router, Tailwind CSS, React, and the React Compiler via Babel. It also defines a path alias @ pointing to the ./src directory to simplify imports within the renderer source code.

import path from "node:path";
import babel from "@rolldown/plugin-babel";
import tailwindcss from "@tailwindcss/vite";
import { tanstackRouter } from "@tanstack/router-plugin/vite";
import react, { reactCompilerPreset } from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [
    tanstackRouter({
      target: "react",
    }),
    tailwindcss(),
    react(),
    babel({ presets: [reactCompilerPreset()] }),
  ],
  resolve: {
    alias: {
      "@": path.resolve(import.meta.dirname, "./src"),
    },
    preserveSymlinks: true,
  },
});

The theme object provides a set of IPC (Inter-Process Communication) methods to manage the application's theme mode (e.g., light, dark) across the Electron main and renderer processes. You can use these methods to retrieve the current mode, explicitly set a mode, or toggle between modes.

import { theme } from './src/ipc/theme/index';

// Get the current theme mode
const currentMode = await theme.getCurrentThemeMode();

// Set a specific theme mode
await theme.setThemeMode('dark');

// Toggle between light and dark modes
await theme.toggleThemeMode();

Use updateAppLanguage to synchronize the application state with the language previously saved in localStorage.

This function:

1. Retrieves the language string from localStorage using LOCAL_STORAGE_KEYS.LANGUAGE.
2. If a language is found, it calls i18.changeLanguage(localLang) on the provided i18n instance.
3. Updates the lang attribute on document.documentElement to match the retrieved language.

If no language is stored in localStorage, the function returns early without making any changes.

import { updateAppLanguage } from "@/actions/language";

// Call this during app initialization to restore user preference
updateAppLanguage(i18n);

The shell object provides methods for interacting with the operating system's shell. Currently, it exposes openExternalLink to allow the application to open URLs or files in the user's default web browser or file explorer via IPC.

import { shell } from './ipc/shell';

// Example usage (conceptually via IPC call):
// shell.openExternalLink('https://example.com');

The window object provides a set of IPC (Inter-Process Communication) methods to control the Electron window from the renderer process. You can use these methods to perform standard window management tasks like closing, maximizing, or minimizing the current window.

import { window } from './path/to/ipc/window';

// Minimize the window
window.minimizeWindow();

// Maximize the window
window.maximizeWindow();

// Close the window
window.closeWindow();

The app object is an IPC (Inter-Process Communication) interface used to retrieve application-level metadata from the main process. It provides access to the current application version and the platform the application is running on.

// Example of how the app IPC object is structured
// Note: Actual usage involves calling these via Electron's ipcRenderer
import { app } from './ipc/app';

console.log(app.appVersion);
console.log(app.currentPlatfom);

Use setTheme(newTheme: ThemeMode) to explicitly set the application theme. This function updates the system theme via IPC, persists the choice in localStorage using the LOCAL_STORAGE_KEYS.THEME key, and updates the document's CSS class (adding/removing the .dark class on document.documentElement).

Supported ThemeMode values typically include 'light', 'dark', or 'system'.

import { setTheme } from '@/actions/theme';

await setTheme('dark');