create-electron-vite-react-ts 0.1.0

package/.editorconfig

@@ -0,0 +1,16 @@
+root = true
+
+[*]
+indent_style = tab
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{js,jsx,ts,tsx,json}]
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false
+

package/.env.example

@@ -0,0 +1,23 @@
+# Copy this file to ".env" at the project root. Main process reads it at startup.
+# Precedence for each key: process environment overrides values below.
+
+# LOG_ENABLED — Master switch for AppLogger. If false, no log file and no terminal output from the logger.
+# Accepted: 1 / true / yes (on) or 0 / false / no (off). Default when unset: true.
+LOG_ENABLED=true
+
+# LOG_FILE — Append log lines to logs/system.YYYYMMDD.log under the project root (when logger is enabled).
+# Default when unset: true for non-packaged runs, false when the app is packaged.
+LOG_FILE=true
+
+# LOG_CONSOLE — Mirror logger lines to the terminal (Node console) when the logger is enabled.
+# Default when unset: true in development, false otherwise.
+LOG_CONSOLE=true
+
+# SCREEN_CENTER — When true: if the window is not maximized and its size is smaller than the target
+# monitor work area, position the window at the horizontal and vertical center of that work area on show.
+# No effect for maximized or full-screen windows. Default when unset: false.
+SCREEN_CENTER=false
+
+# ELECTRON_MENU_ENABLED — If false, removes the application menu bar (Menu.setApplicationMenu(null)).
+# Default when unset: true (menu shown).
+ELECTRON_MENU_ENABLED=true

package/.eslintrc.cjs

@@ -0,0 +1,26 @@
+module.exports = {
+	root: true,
+	env: {
+		browser: true,
+		es2020: true,
+		node: true,
+	},
+	parser: '@typescript-eslint/parser',
+	plugins: ['@typescript-eslint', 'react-hooks', 'react-refresh'],
+	extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
+	ignorePatterns: ['dist'],
+	overrides: [
+		{
+			files: ['**/*.{ts,tsx}'],
+			rules: {
+				'react-refresh/only-export-components': 'warn',
+			},
+		},
+		{
+			files: ['electron/dotenv.ts'],
+			rules: {
+				'@typescript-eslint/no-namespace': 'off',
+			},
+		},
+	],
+}

package/.gitignore

@@ -0,0 +1,39 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-electron
+release
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+.cursor
+.github
+!.github/
+!.github/workflows/
+!.github/workflows/*.yml
+.env
+
+.flows
+flows
+bin
+.nvmrc
+package-lock.json

package/.nvmrc

@@ -0,0 +1 @@
+22.21.1

package/.prettierignore

@@ -0,0 +1,14 @@
+node_modules
+assets
+app
+dist
+build
+*.log
+log
+coverage
+.nyc_output
+*.min.js
+*.min.css
+out
+migration
+resources

package/.prettierrc

@@ -0,0 +1,10 @@
+{
+	"semi": false,
+	"singleQuote": true,
+	"tabWidth": 4,
+	"useTabs": true,
+	"trailingComma": "es5",
+	"printWidth": 10000,
+	"arrowParens": "avoid",
+	"endOfLine": "lf"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Ham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,193 @@
+# electron-vite-react-ts
+
+An Electron desktop application built with **React 18** and **TypeScript**.  
+It uses **[electron-vite](https://electron-vite.org/)** to build the main, preload, and renderer processes together.  
+The baseline includes essential cross-platform desktop capabilities for **Windows, macOS, and Linux** (window lifecycle/state restore, safe IPC bridge, external-link handling, environment-driven startup behavior, and logging).  
+It also presents a production-oriented architecture that helps teams design and extend the exact product they want by separating Electron main, preload, and renderer responsibilities clearly.
+
+
+## Create CLI Usage
+
+Publish this package to npm as `create-electron-vite-react-ts`, then bootstrap a new app:
+
+```bash
+npx create-electron-vite-react-ts my-desktop-app
+cd my-desktop-app
+npm install
+npm run dev
+```
+
+## Requirements
+
+- **Node.js** — LTS recommended (for example, Node 20+)
+- **npm** — package manager
+
+## Getting Started
+
+Install dependencies after cloning the repository:
+
+```bash
+npm install
+```
+
+## npm Scripts
+
+| Command | Description |
+|------|------|
+| `npm run dev` | Development mode — runs Vite dev server and Electron |
+| `npm run build` | Runs TypeScript project reference build, then `electron-vite build` |
+| `npm run start` | Preview built output with `electron-vite preview` |
+| `npm run lint` | Run ESLint |
+| `npm run format` | Run Prettier formatting |
+| `npm run clean` | Clean build outputs and cache (`dist`, `release`, etc.) |
+| `npm run release` | Run `npm run build`, then package with **electron-builder** |
+| `npm run lang` | Switch Windows console code page to UTF-8 (65001) |
+
+> **Note:** Default dev server port is 5173. If occupied, another port (for example 5174) may be selected automatically.
+
+## Project Structure
+
+```text
+.
+├─ electron/
+│  ├─ main.ts              # Main process bootstrap and window lifecycle
+│  ├─ preload.ts           # ContextBridge APIs exposed to renderer
+│  ├─ ipc.ts               # IPC channel constants and handlers
+│  ├─ logger.ts            # Main-process logger (file/console policy)
+│  └─ dotenv.ts            # .env parser + shared global typings
+├─ src/
+│  ├─ renderer/
+│  │  ├─ index.html        # Renderer HTML entry (Vite root)
+│  │  ├─ main.tsx          # Renderer React bootstrap
+│  │  └─ App.tsx           # Root React component
+│  ├─ components/          # Recommended shared UI components folder (create when scaling)
+│  ├─ stores/              # Recommended state stores folder (create when scaling)
+│  ├─ styles/
+│  │  ├─ index.css         # Global styles
+│  │  └─ App.css           # App-level styles
+│  ├─ assets/
+│  │  └─ react.svg
+│  └─ types/
+│     └─ renderer.d.ts     # Window global type declarations
+├─ public/                 # Static assets copied by Vite/electron-vite
+├─ logs/                   # Runtime logs (dev/non-packaged)
+├─ dist/                   # Build output (main/preload/renderer)
+├─ release/                # electron-builder artifacts
+├─ electron.vite.config.ts
+├─ tsconfig.app.json
+├─ tsconfig.electron.json
+└─ package.json
+```
+
+- All build outputs are placed under **`dist/`**: `dist/main/`, `dist/preload/`, and renderer files (`index.html`, `assets/`).
+- `package.json` `main` points to Electron entry at **`dist/main/main.js`**.
+
+## Extension Concepts
+
+This project is organized to scale by separating concerns between Electron main, preload bridge, and renderer UI.
+
+- **Renderer feature growth**
+  - Add feature folders under `src/renderer/` (for example, `src/renderer/features/<feature-name>/`).
+  - Create `src/components/` for reusable presentation/UI components shared across screens.
+  - Create `src/stores/` for app-wide state management (for example, auth/session/app settings).
+  - Keep visual styles in `src/styles/` or feature-local style files.
+  - Keep `main.tsx` as pure bootstrap; avoid placing business logic there.
+
+- **IPC-first desktop capabilities**
+  - Define channel names and handlers in `electron/ipc.ts`.
+  - Expose minimal, safe APIs in `electron/preload.ts` via `contextBridge`.
+  - Consume those APIs in renderer through `window.electronAPI` with typed contracts in `src/types/renderer.d.ts`.
+  - Prefer `invoke/handle` for request-response flows; reserve event channels for streaming/push use cases.
+
+- **Main-process service layering**
+  - As logic grows, split `electron/main.ts` into domain modules (for example, `electron/services/window-state.ts`, `electron/services/menu.ts`).
+  - Keep `main.ts` as orchestration/composition layer.
+
+- **Configuration and environment strategy**
+  - Centralize env parsing/defaults in `electron/dotenv.ts`.
+  - Add new flags in `.env.example` with clear comments and production-safe defaults.
+  - Keep renderer-safe env usage prefixed and explicit.
+
+- **Build and packaging evolution**
+  - Renderer root is `src/renderer`, while output is unified under `dist/`.
+  - Packaging outputs are isolated in `release/` via `build.directories.output`.
+  - Add platform-specific packaging options in `package.json > build` as distribution needs increase.
+
+## Feature Expansion Checklist
+
+When adding a new desktop capability:
+
+1. Add/extend IPC channel and runtime guard in `electron/ipc.ts`.
+2. Expose a narrow preload API in `electron/preload.ts`.
+3. Add/update renderer global typings in `src/types/renderer.d.ts`.
+4. Implement UI flow under `src/renderer/` and styles in `src/styles/`.
+5. Validate with `npm run build` and run-time smoke test in `npm run dev`.
+
+## Development Notes
+
+- In development mode, electron-vite passes the renderer URL through **`ELECTRON_RENDERER_URL`** (kept with fallback support for legacy `VITE_DEV_SERVER_URL`).
+- If Unicode/Korean output is broken in Windows terminal, run `npm run ko` first and execute commands in the same session.
+- Renderer clicks on external `http(s)` links are handled via IPC (`app:open-external`) and opened in the **system default browser**, not inside the app.
+
+## Window State Restore Policy
+
+- **Saved by run mode:** development (with dev server) and production (loading built files) use separate state files.
+  - `window-state.development.json`
+  - `window-state.production.json`
+  - These files are stored in Electron's **`userData`** directory.
+- **Save timing:** state is saved **once right before `close`**, not on every move/resize.
+- **Saved fields:** absolute position (`x`, `y`), size (`width`, `height`), maximized state, **display ID (`displayId`)**, display-relative offsets (`offsetX`, `offsetY`), and work-area size (`workAreaWidth`, `workAreaHeight`).
+- **Restore order:** the window starts with **`show: false`**, then applies saved bounds (or maximize) on `ready-to-show`, and finally calls **`show()`** to reduce flicker and first-paint size jumps.
+- **Multi-monitor behavior:** if the saved monitor is unavailable, it can fall back to primary display. If the same display ID is still valid, saved bounds are prioritized.
+- **Minimized state is not restored** to avoid launching into an invisible window.
+
+## SCREEN_CENTER by Run Mode
+
+- `SCREEN_CENTER` is read from `.env` (or `process.env`) and applies in both development and production.
+- The centering decision runs during startup before the first `show()` and only when all conditions are met:
+  - `SCREEN_CENTER=true`
+  - window is not maximized
+  - window size is smaller than the target display work area
+- Because window-state is separated by run mode, centering can lead to different visible results:
+  - **Development mode:** uses `window-state.development.json`
+  - **Production mode:** uses `window-state.production.json`
+  - If the two mode files store different size/position history, startup placement can differ by mode even with the same `SCREEN_CENTER` value.
+
+## Electron Menu Visibility
+
+- Menu visibility is controlled by `ELECTRON_MENU_ENABLED`.
+- Default behavior is `true` (menu is visible).
+- Set `ELECTRON_MENU_ENABLED=false` to hide the application menu via `Menu.setApplicationMenu(null)` at app startup.
+- This setting is applied in the main process during `app.whenReady()`.
+- Note: hiding the top menu mostly affects Windows/Linux UX; on macOS, global menu-bar conventions still apply at OS level.
+
+## Logging (`logs/`)
+
+- Main process logging (`logger.ts`) can write daily logs to project root as **`logs/system.YYYYMMDD.log`**.
+- **Development mode:** writes to both console and file.
+- **Production mode (non-packaged):** writes to file only.
+- **Packaged app (`app.isPackaged`):** file logging is disabled.
+
+## DevTools in Development
+
+- In development mode (when loading renderer from Vite dev server), the main process opens **DevTools** automatically.
+- In production build mode (loading from `dist`), DevTools is not opened automatically.
+
+## Release Packaging
+
+```bash
+npm run release
+```
+
+- This project sets `build.directories.output` to `release` in `package.json`.
+- Packaging artifacts are generated under root **`release/`**.
+- For platform-specific options, extend the `build` field using the [electron-builder docs](https://www.electron.build/).
+
+---
+
+## Tech Stack
+
+- **Runtime:** Electron 30
+- **Bundler / Dev:** Vite 6, electron-vite 5
+- **UI:** React 18, TypeScript 5
+- **Quality:** ESLint, Prettier

package/bin/create-electron-vite-react-ts.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const packageRoot = path.resolve(__dirname, '..')
+
+const TEMPLATE_DIRS = ['electron', 'public', 'src']
+const TEMPLATE_FILES = [
+	'.editorconfig',
+	'.env.example',
+	'.eslintrc.cjs',
+	'.gitignore',
+	'.nvmrc',
+	'.prettierignore',
+	'.prettierrc',
+	'electron.vite.config.ts',
+	'tsconfig.app.json',
+	'tsconfig.electron.json',
+	'tsconfig.json',
+	'README.md',
+]
+
+const SPECIAL_FILE_SOURCES = {
+	'.gitignore': ['.gitignore', '.npmignore'],
+}
+
+function printUsage() {
+	console.log('Usage: npx create-electron-vite-react-ts <project-name>')
+}
+
+function isValidProjectName(name) {
+	return /^[a-zA-Z0-9._-]+$/.test(name)
+}
+
+function ensureNotExists(targetPath) {
+	if (fs.existsSync(targetPath)) {
+		throw new Error(`Target already exists: ${targetPath}`)
+	}
+}
+
+function copyTemplateFiles(targetRoot) {
+	for (const dir of TEMPLATE_DIRS) {
+		fs.cpSync(path.join(packageRoot, dir), path.join(targetRoot, dir), {
+			recursive: true,
+		})
+	}
+
+	for (const file of TEMPLATE_FILES) {
+		const candidates = SPECIAL_FILE_SOURCES[file] ?? [file]
+		const sourceCandidate = candidates.find(candidate =>
+			fs.existsSync(path.join(packageRoot, candidate))
+		)
+
+		if (!sourceCandidate) {
+			throw new Error(`Template file not found: ${file}`)
+		}
+
+		fs.copyFileSync(path.join(packageRoot, sourceCandidate), path.join(targetRoot, file))
+	}
+}
+
+function createTargetPackageJson(targetRoot, projectName) {
+	const templatePackageJsonPath = path.join(packageRoot, 'package.json')
+	const source = JSON.parse(fs.readFileSync(templatePackageJsonPath, 'utf8'))
+
+	const appPackageJson = {
+		name: projectName.toLowerCase(),
+		private: true,
+		version: '0.1.0',
+		type: 'module',
+		scripts: {
+			dev: source.scripts.dev,
+			build: source.scripts.build,
+			lint: source.scripts.lint,
+			start: source.scripts.start,
+			release: source.scripts.release,
+			format: source.scripts.format,
+			clean: source.scripts.clean,
+			lang: source.scripts.lang,
+		},
+		dependencies: source.dependencies,
+		devDependencies: source.devDependencies,
+		build: source.build,
+		main: source.main,
+	}
+
+	const output = `${JSON.stringify(appPackageJson, null, '\t')}\n`
+	fs.writeFileSync(path.join(targetRoot, 'package.json'), output, 'utf8')
+}
+
+function main() {
+	const projectName = process.argv[2]
+
+	if (!projectName) {
+		printUsage()
+		process.exit(1)
+	}
+
+	if (!isValidProjectName(projectName)) {
+		console.error(`Invalid project name: "${projectName}"`)
+		console.error('Allowed characters: a-z, A-Z, 0-9, dot(.), underscore(_), hyphen(-)')
+		process.exit(1)
+	}
+
+	const targetRoot = path.resolve(process.cwd(), projectName)
+
+	try {
+		ensureNotExists(targetRoot)
+		fs.mkdirSync(targetRoot, { recursive: true })
+		copyTemplateFiles(targetRoot)
+		createTargetPackageJson(targetRoot, projectName)
+
+		console.log('\nProject created successfully.')
+		console.log(`Location: ${targetRoot}\n`)
+		console.log('Next steps:')
+		console.log(`  cd ${projectName}`)
+		console.log('  npm install')
+		console.log('  npm run dev\n')
+	} catch (error) {
+		console.error('\nFailed to create project.')
+		console.error(error instanceof Error ? error.message : String(error))
+		process.exit(1)
+	}
+}
+
+main()