@aryagg/create-super-svelte-library 1.0.16

package/README.md

@@ -0,0 +1,222 @@
+# @aryagg/create-super-svelte-skeleton
+
+A CLI scaffolding tool. One command gives you a fully wired Svelte 5 starter — auth, API layer, i18n, offline support, and 20+ components — ready to run.
+
+---
+
+## 1. Create your project
+
+```bash
+npm create @aryagg/super-svelte-skeleton my-app
+```
+
+This copies the full template into `my-app/` and runs `npm install` automatically.
+
+> `npm create` prepends `create-` to the package name automatically, so `@aryagg/super-svelte-skeleton` resolves to this package (`@aryagg/create-super-svelte-skeleton`).
+
+---
+
+## 2. Set up environment variables
+
+Three env files are included — each loaded automatically by Vite depending on how you run the app:
+
+| File | When it loads |
+|---|---|
+| `.env` | Always (base values, any mode) |
+| `.env.development` | `npm run dev` only |
+| `.env.production` | `npm run build` / `npm run preview` only |
+
+Values in the mode-specific file override `.env`.
+
+Copy the example file as your starting point:
+
+```bash
+cp .env.example .env
+```
+
+**`.env` — shared base**
+```env
+PUBLIC_SITE_NAME="My App"
+PUBLIC_SITE_DESCRIPTION="A high-performance SvelteKit application."
+PUBLIC_API_URL="https://api.myapp.com"
+PUBLIC_CONFIG_ENV="local"
+PUBLIC_BASE_PATH="/app"
+```
+
+**`.env.development` — local dev overrides**
+```env
+PUBLIC_CONFIG_ENV="local"
+PUBLIC_BASE_PATH="/skeleton-local"
+```
+
+**`.env.production` — production build overrides**
+```env
+PUBLIC_CONFIG_ENV="production"
+PUBLIC_BASE_PATH="/prod"
+```
+
+**Rules:**
+- No spaces around `=` — `KEY=VALUE`, not `KEY = VALUE`
+- Variables starting with `PUBLIC_` are available in the browser and server
+- Variables without `PUBLIC_` are server-only
+- After editing any `.env` file, stop and restart `npm run dev`
+
+---
+
+## 3. Configure runtime settings
+
+Open `static/config/config.local.json` for local dev (or `config.prod.json` for production).  
+The active file is picked based on `PUBLIC_CONFIG_ENV` in your `.env`.  
+These files load at runtime — no rebuild needed when you change them.
+
+```json
+{
+  "name": "local"
+}
+```
+
+---
+
+## 4. Run the app
+
+```bash
+cd my-app
+npm run dev
+```
+
+App starts at `http://localhost:5173`.
+
+**Other commands:**
+
+| Command | What it does |
+|---|---|
+| `npm run build` | Production build |
+| `npm run preview` | Preview production build locally |
+| `npm run lint` | Run ESLint |
+| `npm run format` | Format with Prettier |
+| `npm run machine-translate` | Auto-fill missing i18n translation keys |
+
+---
+
+## Project structure
+
+```
+my-app/
+├── src/
+│   ├── routes/
+│   │   ├── (auth)/             ← login, register, forgot/reset password
+│   │   ├── (protected)/        ← dashboard & admin (auth-gated)
+│   │   ├── settings/           ← settings page
+│   │   └── theme/              ← theme preview page
+│   ├── lib/
+│   │   ├── api/                ← HTTP client, endpoints, services, types
+│   │   ├── components/         ← 20+ reusable UI components
+│   │   ├── stores/             ← auth, config, snackbar, loader state
+│   │   ├── composables/        ← Svelte actions (autoFocus, clickOutside)
+│   │   ├── constants/          ← route names, auth keys
+│   │   ├── utils/              ← helpers (string, date, number, URL, theme)
+│   │   ├── types/              ← shared TypeScript interfaces
+│   │   └── styles/             ← global CSS and Tailwind config
+│   ├── hooks.server.ts         ← auth, locale, API key middleware
+│   ├── hooks.client.ts         ← client error handling
+│   └── service-worker.ts       ← offline cache + request queue
+├── messages/
+│   ├── en.json                 ← English translations
+│   ├── es.json                 ← Spanish translations
+│   └── ar.json                 ← Arabic translations
+├── static/
+│   ├── config/
+│   │   ├── config.local.json   ← runtime config for local dev
+│   │   └── config.prod.json    ← runtime config for production
+│   ├── theme-light.css
+│   └── theme-dark.css
+├── .env                        ← your env vars (not committed)
+├── .env.example                ← template for env vars
+├── svelte.config.js
+├── vite.config.ts
+└── package.json
+```
+
+---
+
+## Features
+
+### Authentication
+- Session cookie–based login (httpOnly, secure in production)
+- JWT access + refresh tokens stored in cookie, auto-read by server hooks
+- `/login`, `/register`, `/forgot-password`, `/reset-password` pages — all styled and wired
+- Auth store with role-based helpers (`isAdmin`, `hasRole`, `hasPermission`)
+- 5-level role hierarchy: `GUEST → USER → MANAGER → ADMIN → SUPER_ADMIN`
+- Protected route group `(protected)/` — server layout checks auth before rendering
+
+### API layer
+Located in `src/lib/api/`:
+
+| Folder | Purpose |
+|---|---|
+| `axiosClient.ts` | Configured axios instance — base URL from env, 30s timeout, auto Bearer token, 401 handler |
+| `http.ts` | Response normalizer + offline-queue-aware request wrapper |
+| `endpoints/` | URL constants with a `buildUrl()` param helper |
+| `services/` | Functions for every API call (login, register, me, logout, refresh, list, get, update, remove) |
+| `types/` | TypeScript interfaces for all payloads and responses |
+
+### Offline support
+- Service worker with cache-first for static assets and network-first for API/pages
+- IndexedDB sync queue — requests made offline are stored and replayed when network returns
+- Background Sync API (Chrome/Edge) with postMessage fallback (Safari/Firefox)
+
+### i18n (multi-language)
+- **Paraglide** (`@inlang/paraglide-sveltekit`) — compile-time-safe translations
+- Languages: English, Spanish, Arabic (RTL supported)
+- Language switcher in `Header.svelte` — persists to localStorage
+- To add a language: add `messages/xx.json`, register in `project.inlang/settings.json`, run `npm run machine-translate`
+
+### Theming
+- Light / dark CSS variable themes in `static/theme-light.css` and `theme-dark.css`
+- Theme loaded before first paint — no flash
+- Toggle in `Header.svelte` — persists preference
+- Theme preview page at `/theme`
+
+
+### Developer experience
+- Auto-imports via `unplugin-auto-import` — no need to import `onMount`, `goto`, `fade`, etc.
+- Path aliases — `$components`, `$stores`, `$utils`, `$lib`
+- TypeScript strict mode — unused locals/params flagged
+- ESLint + Prettier preconfigured
+- VS Code extensions and debugger configured out of the box
+- Version polling — layout detects new deploys and reloads automatically
+
+---
+
+## How to publish a new version
+
+```bash
+# 1. Make your changes inside template/ or cli.js
+
+# 2. Bump the version
+npm version patch   # 1.0.1 → 1.0.2
+npm version minor   # 1.0.0 → 1.1.0
+npm version major   # 1.0.0 → 2.0.0
+
+# 3. Publish to npm
+npm publish --access public
+
+# 4. Clear the npx cache so users get the new version immediately
+npx clear-npx-cache
+```
+
+> On Windows, clear manually if needed:
+> `Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"`
+
+### What gets published
+
+Only `cli.js` and the `template/` folder are included in the npm tarball (controlled by the `files` field in `package.json`). This README and other repo files are not published.
+
+### Repo structure
+
+```
+super-duper-skeleton-svelte/
+├── cli.js          ← scaffolding script (entry point)
+├── package.json    ← package config (name, version, bin, files)
+└── template/       ← everything here gets copied into the new project
+```

package/cli.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { execSync } from "child_process";
+
+// ESM doesn't have __dirname (ESM is browser‑compatible, and browsers don’t have __dirname), so we derive it from the current file's URL
+const __dirname = path.dirname(fileURLToPath(import.meta.url)); //( import.meta.url  full URL of the current file.)
+
+// Second CLI arg is the project name; default to "svelte-library" if omitted
+const target = process.argv[2] || "svelte-library";
+
+// Bail early if the target folder already exists to avoid overwriting anything
+if (fs.existsSync(target)) {
+  console.error(`Error: directory "${target}" already exists.`);
+  process.exit(1);
+}
+
+// The template folder ships inside the npm package next to this file
+const templateDir = path.join(__dirname, "template");
+if (!fs.existsSync(templateDir)) {
+  console.error(`Error: template directory not found at ${templateDir}`);
+  process.exit(1);
+}
+
+console.log(`Creating project: ${target}`);
+
+// These top-level folders inside the template are dev/build artifacts — skip them
+const SKIP_DIRS = new Set(["node_modules", ".svelte-kit", ".git", ".claude"]);
+
+try {
+fs.cpSync(templateDir, target, {
+	recursive: true,
+      // Filter runs on absolute paths, so we use relative path from templateDir
+    // to avoid false matches against "node_modules" in the npm cache path itself
+	filter: (src) => {
+		const rel = path.relative(templateDir, src);
+
+		// Keep root itself
+		if (!rel) return true;
+
+		const parts = rel.split(path.sep);
+
+		// Skip only actual directories named in SKIP_DIRS
+		return !parts.some((part) => SKIP_DIRS.has(part));
+	}
+});
+
+  // npm strips .gitignore from published packages, so the template stores them as _gitignore
+  const renameGitignores = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) renameGitignores(full);
+      else if (entry.name === "_gitignore") fs.renameSync(full, path.join(dir, "."));
+    }
+  };
+  renameGitignores(target);
+
+  // Rename the package to match the new project folder and drop the private flag
+  const pkgPath = path.join(target, "package.json");
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  pkg.name = path.basename(target);
+  delete pkg.private;
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, "\t") + "\n");
+
+  console.log("Installing dependencies...");
+  // Run npm install inside the newly created project folder
+  execSync("npm install", { cwd: target, stdio: "inherit" });
+
+  console.log("\nDone!");
+  console.log(`  cd ${target}`);
+  console.log("  npm run dev");
+} catch (err) {
+  console.error("Error during scaffolding:", err.message);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@aryagg/create-super-svelte-library",
+  "version": "1.0.16",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "create-super-svelte-library": "cli.js"
+  },
+  "files": [
+    "cli.js",
+    "template"
+  ]
+}

package/template/.prettierignore

@@ -0,0 +1,9 @@
+# Package Managers
+package-lock.json
+pnpm-lock.yaml
+yarn.lock
+bun.lock
+bun.lockb
+
+# Miscellaneous
+/static/

package/template/.prettierrc

@@ -0,0 +1,15 @@
+{
+	"useTabs": true,
+	"singleQuote": true,
+	"trailingComma": "none",
+	"printWidth": 100,
+	"plugins": ["prettier-plugin-svelte"],
+	"overrides": [
+		{
+			"files": "*.svelte",
+			"options": {
+				"parser": "svelte"
+			}
+		}
+	]
+}

package/template/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+	"recommendations": ["svelte.svelte-vscode", "esbenp.prettier-vscode", "dbaeumer.vscode-eslint"]
+}

package/template/README.md

@@ -0,0 +1,65 @@
+# Svelte library
+
+Everything you need to build a Svelte library, powered by [`sv`](https://npmjs.com/package/sv).
+
+Read more about creating a library [in the docs](https://svelte.dev/docs/kit/packaging).
+
+## Creating a project
+
+If you're seeing this, you've probably already done this step. Congrats!
+
+```sh
+# create a new project in the current directory
+npx sv create
+
+# create a new project in my-app
+npx sv create my-app
+```
+
+To recreate this project with the same configuration:
+
+```sh
+# recreate this project
+npx sv@0.16.1 create --template library --types ts --add prettier eslint --install npm ui-kit
+```
+
+## Developing
+
+Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+
+```sh
+npm run dev
+
+# or start the server and open the app in a new browser tab
+npm run dev -- --open
+```
+
+Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app.
+
+## Building
+
+To build your library:
+
+```sh
+npm pack
+```
+
+To create a production version of your showcase app:
+
+```sh
+npm run build
+```
+
+You can preview the production build with `npm run preview`.
+
+> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
+
+## Publishing
+
+Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
+
+To publish your library to [npm](https://www.npmjs.com):
+
+```sh
+npm publish
+```

package/template/_gitignore

@@ -0,0 +1,24 @@
+node_modules
+
+# Output
+.output
+.vercel
+.netlify
+.wrangler
+/.svelte-kit
+/build
+/dist
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.env.*
+!.env.example
+!.env.test
+
+# Vite
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*

package/template/eslint.config.js

@@ -0,0 +1,41 @@
+import prettier from 'eslint-config-prettier';
+import path from 'node:path';
+import js from '@eslint/js';
+import svelte from 'eslint-plugin-svelte';
+import { defineConfig, includeIgnoreFile } from 'eslint/config';
+import globals from 'globals';
+import ts from 'typescript-eslint';
+
+const gitignorePath = path.resolve(import.meta.dirname, '.gitignore');
+
+export default defineConfig(
+	includeIgnoreFile(gitignorePath),
+	js.configs.recommended,
+	ts.configs.recommended,
+	svelte.configs.recommended,
+	prettier,
+	svelte.configs.prettier,
+	{
+		languageOptions: { globals: { ...globals.browser, ...globals.node } },
+		rules: {
+			// typescript-eslint strongly recommend that you do not use the no-undef lint rule on TypeScript projects.
+			// see: https://typescript-eslint.io/troubleshooting/faqs/eslint/#i-get-errors-from-the-no-undef-rule-about-global-variables-not-being-defined-even-though-there-are-no-typescript-errors
+			'no-undef': 'off'
+		}
+	},
+	{
+		files: ['**/*.svelte', '**/*.svelte.ts', '**/*.svelte.js'],
+		languageOptions: {
+			parserOptions: {
+				projectService: true,
+				extraFileExtensions: ['.svelte'],
+				parser: ts.parser
+			}
+		}
+	},
+	{
+		// Override or add rule settings here, such as:
+		// 'svelte/button-has-type': 'error'
+		rules: {}
+	}
+);