Obsidian Multi-Environment Setup

Overview

Configure separate development, testing, and production vaults for Obsidian plugin work. Covers vault templates for team onboarding, environment-specific plugin settings, sync strategies, and

.obsidian/

directory management across environments.

Prerequisites

Obsidian desktop app installed
Node.js 18+ and npm/pnpm for plugin builds
Git for version control (recommended)
Basic understanding of symlinks and file system operations

Instructions

Step 1: Create the Environment Structure

Set up three isolated vaults -- dev, test, and prod:

bash

# Base directory for all environments
mkdir -p ~/obsidian-envs/{dev,test,prod}

# Dev vault: your working vault with symlinked plugin source
mkdir -p ~/obsidian-envs/dev/.obsidian/plugins/your-plugin
mkdir -p ~/obsidian-envs/dev/sandbox  # scratch notes for testing

# Test vault: clean environment for QA
mkdir -p ~/obsidian-envs/test/.obsidian/plugins/your-plugin
mkdir -p ~/obsidian-envs/test/test-data

# Prod vault: mirrors real user setup
mkdir -p ~/obsidian-envs/prod/.obsidian/plugins/your-plugin

Step 2: Symlink Plugin Source for Development

In the dev vault, symlink your plugin's build output so changes appear immediately:

bash

# Remove the empty plugin directory in dev
rm -rf ~/obsidian-envs/dev/.obsidian/plugins/your-plugin

# Symlink to your plugin's repo (contains manifest.json, main.js, styles.css)
ln -s /path/to/your-plugin ~/obsidian-envs/dev/.obsidian/plugins/your-plugin

For hot reload during development, use the Hot Reload plugin:

bash

# Clone hot-reload into dev vault's plugins
git clone https://github.com/pjeby/hot-reload.git \
  ~/obsidian-envs/dev/.obsidian/plugins/hot-reload

Then enable both your plugin and hot-reload in

.obsidian/community-plugins.json

json

["your-plugin", "hot-reload"]

Step 3: Environment-Specific Plugin Settings

Each vault gets its own

data.json

for your plugin. Create a config factory:

typescript

// config/environments.ts
interface PluginConfig {
  debugMode: boolean;
  logLevel: 'debug' | 'info' | 'warn' | 'error';
  apiEndpoint: string;
  featureFlags: Record<string, boolean>;
}

const ENV_CONFIGS: Record<string, Partial<PluginConfig>> = {
  dev: {
    debugMode: true,
    logLevel: 'debug',
    apiEndpoint: 'http://localhost:3000',
    featureFlags: { experimentalEditor: true, betaSync: true },
  },
  test: {
    debugMode: true,
    logLevel: 'info',
    apiEndpoint: 'https://staging.api.example.com',
    featureFlags: { experimentalEditor: true, betaSync: false },
  },
  prod: {
    debugMode: false,
    logLevel: 'error',
    apiEndpoint: 'https://api.example.com',
    featureFlags: {},
  },
};

export function detectEnvironment(vaultPath: string): string {
  if (vaultPath.includes('obsidian-envs/dev')) return 'dev';
  if (vaultPath.includes('obsidian-envs/test')) return 'test';
  return 'prod';
}

export function getConfig(env: string): PluginConfig {
  const defaults: PluginConfig = {
    debugMode: false,
    logLevel: 'error',
    apiEndpoint: '',
    featureFlags: {},
  };
  return { ...defaults, ...ENV_CONFIGS[env] };
}

Use it in your plugin's

onload()

typescript

async onload() {
  const vaultPath = (this.app.vault.adapter as any).basePath;
  const env = detectEnvironment(vaultPath);
  const config = getConfig(env);
  console.log(`[your-plugin] Running in ${env} mode`);

  if (config.debugMode) {
    // Register debug commands only in dev/test
    this.addCommand({
      id: 'dump-state',
      name: 'Dump Plugin State (debug)',
      callback: () => console.log(JSON.stringify(this.settings, null, 2)),
    });
  }
}

Step 4: Vault Templates for Team Onboarding

Create a template vault that new team members clone:

vault-template/
  .obsidian/
    app.json              # Standard app settings
    appearance.json       # Theme and font settings
    hotkeys.json          # Team-standard keybindings
    community-plugins.json  # Approved plugin list
    plugins/              # Pre-configured plugin data.json files
      dataview/data.json
      templater-obsidian/data.json
  templates/              # Note templates (daily, meeting, project)
    daily.md
    meeting.md
    project-kickoff.md
  README.md               # Vault orientation guide

Script to provision a new team member's vault:

bash

#!/bin/bash
# provision-vault.sh <username> <role>
USERNAME=$1
ROLE=${2:-editor}

VAULT_DIR=~/obsidian-team-vaults/$USERNAME
cp -r vault-template "$VAULT_DIR"

# Inject user-specific settings
cat > "$VAULT_DIR/.obsidian/plugins/rbac-plugin/data.json" <<EOF
{
  "userEmail": "${USERNAME}@company.com",
  "role": "${ROLE}"
}
EOF

echo "Vault provisioned at $VAULT_DIR for $USERNAME ($ROLE)"

Step 5: Sync Strategies

Choose based on your team's needs:

Git sync (best for plugin developers):

bash

cd ~/obsidian-envs/prod
git init
cat > .gitignore <<'EOF'
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.obsidian/cache
.trash/
EOF
git add -A && git commit -m "Initial vault state"

Pair with the Obsidian Git plugin for auto-commit/push on a schedule.

Obsidian Sync (best for non-technical teams): Configure in Settings > Sync. Selective sync lets you exclude

.obsidian/plugins/

on certain devices to prevent config conflicts.

iCloud/Dropbox (simplest, most fragile): Place the vault inside the sync folder. Avoid editing on multiple devices simultaneously.

.obsidian/

conflicts are common -- keep a backup.

Step 6: Managing .obsidian/ Across Environments

The

.obsidian/

directory holds all configuration. Key files and their sync behavior:

File	Sync across envs?	Why
`app.json`	Yes	Core settings should be consistent
`appearance.json`	Yes	Theme consistency
`community-plugins.json`	Per-env	Dev may have debug plugins
`hotkeys.json`	Yes	Muscle memory matters
`workspace.json`	Never	Layout is per-device
`plugins/*/data.json`	Per-env	Settings differ by environment

Script to sync safe configs from prod to other environments:

bash

#!/bin/bash
# sync-config.sh -- copy safe configs from prod to dev/test
SAFE_FILES="app.json appearance.json hotkeys.json"
SRC=~/obsidian-envs/prod/.obsidian

for env in dev test; do
  DST=~/obsidian-envs/$env/.obsidian
  for f in $SAFE_FILES; do
    cp "$SRC/$f" "$DST/$f" 2>/dev/null && echo "Synced $f to $env"
  done
done

Output

Three isolated vaults (dev/test/prod) with independent plugin configurations
Symlinked plugin source in dev vault with hot reload
Environment detection and config switching in plugin code
Vault template and provisioning script for team onboarding
Sync strategy configured (Git, Obsidian Sync, or cloud)
```
.obsidian/
```
management scripts for consistent cross-env config

Error Handling

Issue	Cause	Solution
Symlink not working	Permission denied on Windows	Run terminal as Administrator, or use `mklink /D`
Plugin not appearing in dev vault	Symlink target missing `manifest.json`	Run `npm run build` first; ensure `main.js` exists
Wrong config loaded	Vault path detection failed	Check `basePath` matches expected pattern
Hot reload not triggering	`.hotreload` file missing	Create empty `.hotreload` in plugin directory
Sync conflict on `workspace.json`	Multiple devices open same vault	Add `workspace.json` to `.gitignore`
Test vault has stale data	Forgot to refresh after plugin update	Copy latest build artifacts: `manifest.json` , `main.js` , `styles.css`

Examples

Solo developer workflow: Dev vault symlinked to plugin repo with hot reload. Test vault gets

npm run build

output copied in manually for final QA. Prod vault is your daily-driver vault with the released version from BRAT or community plugins.

Team onboarding: Run

provision-vault.sh alice editor

to create Alice's vault from the team template. She opens it in Obsidian, and all approved plugins with team-standard settings are pre-configured.

CI testing across Obsidian versions: Create a headless test vault with your plugin installed. Use

obsidian-cli

or Electron automation to open the vault, run plugin commands, and verify output. Repeat for each Obsidian version in your support matrix.

Resources

Next Steps

For monitoring and logging across environments, see

obsidian-observability

. For access control on shared vaults, see

obsidian-enterprise-rbac

obsidian-multi-env-setup

NPX Install

Tags

SKILL.md Content

Obsidian Multi-Environment Setup

Overview

Prerequisites

Instructions

Step 1: Create the Environment Structure

Step 2: Symlink Plugin Source for Development

Step 3: Environment-Specific Plugin Settings

Step 4: Vault Templates for Team Onboarding

Step 5: Sync Strategies

Step 6: Managing .obsidian/ Across Environments

Output

Error Handling

Examples

Resources

Next Steps