Skip to content
NextDNS Blocker

Configuration Overview

NextDNS Blocker uses two main configuration files:

  • .env: API credentials and environment settings
  • config.json: Domain schedules, blocklist, and allowlist

Configuration Locations

Section titled “Configuration Locations”
PlatformLocation
macOS/Linux~/.config/nextdns-blocker/
Windows%APPDATA%\nextdns-blocker\

Quick Reference

Section titled “Quick Reference”

.env (Credentials)

Section titled “.env (Credentials)”
Terminal window
# Required
NEXTDNS_API_KEY=your_api_key
NEXTDNS_PROFILE_ID=abc123


# Optional
API_TIMEOUT=10
API_RETRIES=3
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
DISCORD_NOTIFICATIONS_ENABLED=true

config.json (Domains)

Section titled “config.json (Domains)”
{
  "version": "1.0",
  "settings": {
    "timezone": "America/New_York",
    "editor": null
  },
  "categories": [...],
  "blocklist": [...],
  "allowlist": [...]
}

Configuration Sections

Section titled “Configuration Sections”
SectionGuideDescription
EnvironmentEnvironment VariablesAPI keys, timeouts, notifications
Structureconfig.jsonFile structure and fields
SchedulesSchedulesTime-based access rules
CategoriesCategoriesGroup domains with shared settings
BlocklistBlocklistDomains to manage
AllowlistAllowlistDomain exceptions
DelaysUnblock DelayFriction-based protection
TimezoneTimezoneSchedule evaluation timezone

Managing Configuration

Section titled “Managing Configuration”

View Current Config

Section titled “View Current Config”
Terminal window
nextdns-blocker config show

Edit Configuration

Section titled “Edit Configuration”
Terminal window
nextdns-blocker config edit

Validate Configuration

Section titled “Validate Configuration”
Terminal window
nextdns-blocker config validate

Set Specific Values

Section titled “Set Specific Values”
Terminal window
nextdns-blocker config set timezone America/Los_Angeles
nextdns-blocker config set editor vim

Configuration Best Practices

Section titled “Configuration Best Practices”

Security

Section titled “Security”
  1. Never commit .env to version control
  2. Keep API credentials private
  3. Use environment variables in CI/CD

Organization

Section titled “Organization”
  1. Use descriptive description fields
  2. Group related domains with similar schedules
  3. Document protected domains clearly

Testing

Section titled “Testing”
  1. Use config validate before syncing
  2. Use sync --dry-run to preview changes
  3. Test schedule logic at boundary times

Example Configurations

Section titled “Example Configurations”

Ready-to-use templates in the examples/ directory:

TemplateUse Case
minimal.jsonQuick start
work-focus.jsonProductivity
gaming.jsonGaming platforms
social-media.jsonSocial networks
parental-control.jsonProtected blocking
study-mode.jsonStudent focus

Copy a template:

Terminal window
cp examples/work-focus.json ~/.config/nextdns-blocker/config.json
nextdns-blocker config edit  # Customize

Next Steps

Section titled “Next Steps”