Feature: Added support for remote workspaces including code-server from Coder

.changeset/ninety-boats-brake.md

@@ -0,0 +1,8 @@
+---
+'@evidence-dev/evidence': minor
+'evidence-vscode': minor
+'@evidence-dev/sdk': minor
+'@evidence-dev/tailwind': patch
+---
+
+Added better support for remote environments including running in code-server with auto-port forwarding, also added a feature for disabling the automatic building of sources by the dev server

.changeset/stale-lizards-wink.md

@@ -0,0 +1,7 @@
+---
+'@evidence-dev/evidence': minor
+'@evidence-dev/sdk': minor
+'@evidence-dev/tailwind': minor
+---
+
+This PR enhances Evidence's development experience and proxy support with improvements to dev command CLI options and developer workflows.

.tool-versions

@@ -0,0 +1,2 @@
+nodejs 22.19.0
+pnpm 10.17.0

CONTRIBUTING.md

@@ -42,6 +42,13 @@ To request a feature, a new data source, or ask for help, create a GitHub discus
 
 ### Getting Started
 
+Evidence development can be done in two ways:
+
+1. **Repository Development** (recommended): Work directly in the Evidence repository using the example project
+2. **Local Package Linking**: Link your existing Evidence project to local Evidence packages
+
+#### Repository Development
+
 Follow these steps to test your changes, once you've started the example project (per steps below),
 you should be able to open the `Evidence Development Workspace` on `localhost:3000`. Any subsequent changes you make will be reflected on the website.
 
@@ -75,6 +82,16 @@ pnpm run dev:core-components
 pnpm run dev:example-project
 ```
 
+#### Local Package Linking
+
+If you prefer to develop using your existing Evidence project instead of the example project:
+
+1. Clone and build the Evidence repository
+2. Link local packages in your project's `package.json`
+3. Configure Tailwind CSS and Vite for local development
+
+For detailed setup instructions, see [DEVELOP.md](./DEVELOP.md).
+
 #### Cannot find package Error
 
 If you get: `Error [ERR_MODULE_NOT_FOUND]: Cannot find package [...]`. You might need to clean the `caches`

DEVELOP.md

@@ -0,0 +1,156 @@
+# Development Setup with Local Evidence Packages
+
+## When to Use This Guide
+
+**Most Evidence development should use the standard process:** Work directly in the Evidence repository using the example project, as documented in [CONTRIBUTING.md](./CONTRIBUTING.md). This is simpler, faster, and recommended for most contributors developing Evidence components and framework code.
+
+**Use this local package linking approach only when:**
+- **Developing the Evidence CLI** - Testing template population, file watching, or CLI-specific features
+- **End-to-end testing** - Testing the complete Evidence user experience with real project structures
+- **Testing with your own Evidence project** - You need to validate changes against your specific setup
+
+The key difference: the example project uses `vite dev` directly and bypasses Evidence's CLI template system, while real Evidence projects use `evidence dev` which converts Evidence project structure (pages/, sources/, queries/) into SvelteKit structure.
+
+## Overview
+
+This guide explains how to link your existing Evidence project to local Evidence packages for development, allowing you to edit Evidence source code and see changes immediately in your own project.
+
+## Prerequisites
+
+- An existing Evidence project
+- Local clone of the Evidence repository
+- Node.js and npm installed
+
+## Step 1: Clone Evidence Repository
+
+```bash
+git clone https://github.com/evidence-dev/evidence.git
+cd evidence
+git checkout release-2025-02-20  # Use stable release branch
+npm install
+npm run build
+```
+
+## Step 2: Configure Your Evidence Project
+
+In your Evidence project's `package.json`, replace Evidence package references with local file paths:
+
+```json
+{
+  "dependencies": {
+    "@evidence-dev/core-components": "file:../evidence/packages/ui/core-components",
+    "@evidence-dev/component-utilities": "file:../evidence/packages/lib/component-utilities",
+    "@evidence-dev/sdk": "file:../evidence/packages/lib/sdk",
+    "@evidence-dev/db-commons": "file:../evidence/packages/lib/db-commons",
+    "@evidence-dev/universal-sql": "file:../evidence/packages/lib/universal-sql",
+    "@evidence-dev/tailwind": "file:../evidence/packages/ui/tailwind"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-static": "3.0.1",
+    "@sveltejs/kit": "2.8.4",
+    "@sveltejs/vite-plugin-svelte": "3.1.2",
+    "@tailwindcss/vite": "^4.0.0",
+    "svelte": "4.2.19",
+    "vite": "5.4.14"
+  }
+}
+```
+
+**Important**: Use exact versions to match Evidence's dependencies, especially Svelte 4.2.19.
+
+## Step 3: Fix Tailwind CSS Content Scanning
+
+When using local packages, Tailwind CSS v4 cannot find Evidence component files. You need to update the Evidence Tailwind configuration:
+
+Edit `/path/to/evidence/packages/ui/tailwind/src/config/config.js`:
+
+```javascript
+export const config = {
+  content: [
+    // Core Evidence components source files (for local development)
+    '../../../core-components/src/**/*.{html,js,svelte,ts,md}',
+    './node_modules/@evidence-dev/core-components/src/**/*.{html,js,svelte,ts,md}',
+    './node_modules/@evidence-dev/core-components/dist/**/*.{html,js,svelte,ts,md}',
+
+    // Additional Evidence UI packages
+    '../../../*/src/**/*.{html,js,svelte,ts,md}',
+    './node_modules/@evidence-dev/*/src/**/*.{html,js,svelte,ts,md}',
+    './node_modules/@evidence-dev/*/dist/**/*.{html,js,svelte,ts,md}',
+
+    // Consumer project files
+    './src/**/*.{html,js,svelte,ts,md}',
+    './.evidence/template/src/**/*.{html,js,svelte,ts,md}'
+  ],
+  // ... rest of existing config
+}
+```
+
+## Step 4: Update Vite Configuration
+
+In your project's `vite.config.js`, exclude core-components from optimization:
+
+```javascript
+export default {
+  // ... other config
+  optimizeDeps: {
+    exclude: [
+      'svelte-icons',
+      '@evidence-dev/universal-sql',
+      '$evidence/config',
+      '$evidence/themes',
+      '@evidence-dev/core-components'  // Add this line
+    ]
+  }
+}
+```
+
+## Step 5: Install Dependencies and Run
+
+```bash
+# Install with force to handle local package linking
+npm install --force
+
+# Start development server
+npm run dev
+```
+
+## Why This Setup is Needed
+
+### Svelte Version Compatibility
+Evidence is built with Svelte 4.2.19, but newer projects might default to Svelte 5. Version mismatches cause compilation errors.
+
+### Tailwind CSS Content Scanning
+Tailwind CSS v4 scans files to determine which utility classes to generate. When using local packages instead of published npm packages, the file paths change and Tailwind cannot find Evidence component files, resulting in missing CSS rules and broken styling.
+
+### Vite Dependency Optimization
+Vite pre-bundles dependencies for faster loading. Local packages need different handling than published packages, so core-components should be excluded from optimization.
+
+## Troubleshooting
+
+### Styling Issues (Oversized Icons, Missing CSS)
+This typically indicates Tailwind isn't finding Evidence component files. Verify:
+1. The Tailwind config includes the correct content paths
+2. The Evidence repository is built (`npm run build` in Evidence repo)
+3. File paths in `package.json` are correct relative to your project
+
+### Build Errors
+Check that:
+1. Svelte versions match exactly (4.2.19)
+2. SvelteKit version is compatible (2.8.4)
+3. All local package paths exist and are built
+
+### Force Reinstall
+If packages seem corrupted:
+```bash
+rm -rf node_modules package-lock.json
+npm install --force
+```
+
+## Development Workflow
+
+1. Make changes to Evidence source code
+2. Build Evidence packages: `cd evidence && npm run postinstall`e
+3. Changes should automatically reflect in your project (HMR)
+4. For major changes, restart your dev server
+
+This setup allows you to develop Evidence components locally while maintaining a working project environment.

packages/evidence/cli.js

@@ -8,7 +8,7 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import sade from 'sade';
 import { logQueryEvent } from '@evidence-dev/telemetry';
-import { enableDebug, enableStrictMode } from '@evidence-dev/sdk/utils';
+import { enableDebug, enableStrictMode, disableHmr } from '@evidence-dev/sdk/utils';
 import { loadEnv } from 'vite';
 import { createHash } from 'crypto';
 
@@ -60,7 +60,7 @@ const runFileWatcher = function (watchPatterns) {
 
 	var watchers = [];
 
-	watchPatterns.forEach((pattern, item) => {
+	watchPatterns.filter(p => p?.disabled !== true).forEach((pattern, item) => {
 		watchers[item] = chokidar.watch(path.join(pattern.sourceRelative, pattern.filePattern), {
 			ignored: ignoredFiles
 		});
@@ -131,11 +131,13 @@ const watchPatterns = [
 		filePattern: '**'
 	}, // static files (eg images)
 	{
+		mnemonic: 'sources',
 		sourceRelative: './sources/',
 		targetRelative: './.evidence/template/sources/',
 		filePattern: '**'
 	}, // source files (eg csv files)
 	{
+		mnemonic: 'queries',
 		sourceRelative: './queries',
 		targetRelative: './.evidence/template/queries',
 		filePattern: '**'
@@ -145,7 +147,11 @@ const watchPatterns = [
 		targetRelative: './.evidence/template/src/components/',
 		filePattern: '**'
 	}, // custom components
-	{ sourceRelative: '.', targetRelative: './.evidence/template/src/', filePattern: 'app.css' }, // custom theme file
+	{ 
+		sourceRelative: '.', 
+		targetRelative: './.evidence/template/src/', 
+		filePattern: 'app.css' 
+	}, // custom theme file
 	{
 		sourceRelative: './partials',
 		targetRelative: './.evidence/template/partials',
@@ -161,6 +167,7 @@ function removeStaticDir(dir) {
 const strictMode = function () {
 	enableStrictMode();
 };
+
 const buildHelper = function (command, args) {
 	const watchers = runFileWatcher(watchPatterns);
 	const flatArgs = flattenArguments(args);
@@ -177,7 +184,7 @@ const buildHelper = function (command, args) {
 			// used for source query HMR
 			EVIDENCE_DATA_URL_PREFIX: process.env.EVIDENCE_DATA_URL_PREFIX ?? 'static/data',
 			EVIDENCE_DATA_DIR: process.env.EVIDENCE_DATA_DIR ?? './static/data',
-			EVIDENCE_IS_BUILDING: 'true'
+			EVIDENCE_IS_BUILDING: 'true',
 		}
 	});
 	// Copy the outputs to the root of the project upon successful exit
@@ -234,6 +241,8 @@ const prog = sade('evidence');
 
 prog
 	.command('dev')
+	.option('--disable-hmr', 'Disables hot-reloading of certain features [sources,queries]')
+	.option('--disable-watchers', 'Disables watching certain directories [sources,queries]')
 	.option('--debug', 'Enables verbose console logs')
 	.describe('launch the local evidence development environment')
 	.action((args) => {
@@ -243,6 +252,33 @@ prog
 			delete args.debug;
 		}
 
+		if (args['disable-watchers']) {
+			const directories = args['disable-watchers'].split(/\W/).filter(v => v.length > 0);
+			const mnemonics = watchPatterns.filter(p => Object.hasOwn(p, 'mnemonic')).map(p => p.mnemonic);
+			if (directories.some(v => !mnemonics.includes(v))) {
+				console.warn(chalk.yellow(`Unknown watch directory/directories: "${args['disable-watchers']}"`));
+				console.info(`Directories for which watching can be disabled are: ${mnemonics.join(', ') }`);
+				process.exit(1);
+			}
+
+			watchPatterns.forEach(p => {
+				p.disabled = Object.hasOwn(p, 'mnemonic') && directories.includes(p.mnemonic);
+			});
+
+			console.info(chalk.bold(`These directories will not be watched: ${directories.join(', ')}`));
+			delete args['disable-watchers'];
+		}
+
+		if (args['disable-hmr']) {
+			try {
+				disableHmr(args['disable-hmr'].split(/\W/).filter(v => v.length > 0));
+			} catch (_) {
+				console.warn(chalk.yellow(`Unknown HMR feature(s): "${args['disable-hmr']}"`));
+			}
+
+			delete args['disable-hmr'];
+		}
+
 		loadEnvFile();
 
 		const manifestExists = fs.lstatSync(
@@ -280,7 +316,7 @@ ${chalk.bold('[!] Unable to load source manifest')}
 				...process.env,
 				// used for source query HMR
 				EVIDENCE_DATA_URL_PREFIX: process.env.EVIDENCE_DATA_URL_PREFIX ?? 'static/data',
-				EVIDENCE_DATA_DIR: process.env.EVIDENCE_DATA_DIR ?? './static/data'
+				EVIDENCE_DATA_DIR: process.env.EVIDENCE_DATA_DIR ?? './static/data',
 			}
 		});