Project Configuration

This page details how to properly configure your ZTO SaaS Starter Kit project. We cover setting up essential environment variables, adjusting basic project settings, and other crucial configuration steps. Proper configuration will ensure your project runs smoothly and takes full advantage of all features.

Environment Variable Configuration

Our project uses different .env files for various environments and purposes:

  • .env: Contains variables for all environments.
  • .env.development: Specific variables for the development environment.
  • .env.production: Specific variables for the production environment.
  • .env.local: Contains all sensitive and private variables.

Important note about .env.local:

  • We provide a .env.local.example file in the repository.
  • You need to rename this file to .env.local and update it with your own values.
  • The purpose of .env.local is to store sensitive information like API keys, database credentials, and other private configuration details.
  • .env.local is included in .gitignore to prevent accidental commits of sensitive data.

1. Open and modify the .env file located in the apps/web directory.

.env

# Website URL
NEXT_PUBLIC_SITE_URL=
# Product name
NEXT_PUBLIC_PRODUCT_NAME=
# Website title
NEXT_PUBLIC_SITE_TITLE=
# Website description
NEXT_PUBLIC_SITE_DESCRIPTION=
# Default theme mode (light/dark)
NEXT_PUBLIC_DEFAULT_THEME_MODE=
# Light theme color
NEXT_PUBLIC_THEME_COLOR=
# Dark theme color
NEXT_PUBLIC_THEME_COLOR_DARK=
# Enable password authentication
NEXT_PUBLIC_AUTH_PASSWORD=
# Enable magic link authentication
NEXT_PUBLIC_AUTH_MAGIC_LINK=
# CAPTCHA site key (cloudflare)
NEXT_PUBLIC_CAPTCHA_SITE_KEY=
# Billing provider (stripe/lemon-squeezy)
NEXT_PUBLIC_BILLING_PROVIDER=
# CMS client
CMS_CLIENT=
# Keystatic content path
NEXT_PUBLIC_KEYSTATIC_CONTENT_PATH=./content
# Locales path
NEXT_PUBLIC_LOCALES_PATH=apps/web/public/locales
# Enable theme toggle
NEXT_PUBLIC_ENABLE_THEME_TOGGLE=true
# Enable personal account deletion
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_DELETION=true
# Enable personal account billing
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING=true
# Enable team accounts deletion
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_DELETION=true
# Enable team accounts billing
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING=true
# Enable team accounts feature
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS=true
# Enable team accounts creation
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_CREATION=true
# Language priority setting (application/user)
NEXT_PUBLIC_LANGUAGE_PRIORITY=application

2. Open and modify the .env.development file located in the apps/web directory.

.env.development

# Supabase project URL for local development
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
# Secret for Supabase database webhooks
SUPABASE_DB_WEBHOOK_SECRET=WEBHOOKSECRET
# Email sender address for development
EMAIL_SENDER=test@zto.dev
# SMTP server port for email sending in development
EMAIL_PORT=54325
# SMTP server host for email sending in development
EMAIL_HOST=localhost
# Whether to use TLS for email sending
EMAIL_TLS=false
# SMTP server username for email sending in development
EMAIL_USER=user
# SMTP server password for email sending in development
EMAIL_PASSWORD=password
# Contact email address for development
CONTACT_EMAIL=test@zto.dev
# Email service provider (nodemailer for development)
MAILER_PROVIDER=nodemailer

3. Open and modify the .env.production located in the apps/web directory.

.env.development

# Supabase project URL for local development
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
# Secret for Supabase database webhooks
SUPABASE_DB_WEBHOOK_SECRET=WEBHOOKSECRET
# Email sender address for development
EMAIL_SENDER=test@zto.dev
# SMTP server port for email sending in development
EMAIL_PORT=54325
# SMTP server host for email sending in development
EMAIL_HOST=localhost
# Whether to use TLS for email sending
EMAIL_TLS=false
# SMTP server username for email sending in development
EMAIL_USER=user
# SMTP server password for email sending in development
EMAIL_PASSWORD=password
# Contact email address for development
CONTACT_EMAIL=test@zto.dev
# Email service provider (nodemailer for development)
MAILER_PROVIDER=nodemailer

4. Open and modify the .env.local located in the apps/web directory.

  • Copy .env.local.example to .env.local:

.env.local

cp .env.local.example .env.local
  • Open .env.local and update the variables with your specific values.

Never commit .env.local to version control. Keep your sensitive information private.

Application Configuration

1. Common Configuration

We recommend setting the config by using environment variables. This way, you can easily adjust the project settings for different environments.

Open apps/web/src/app.config.ts and modify the following settings

apps/web/src/app.config.ts

{
  name: process.env.NEXT_PUBLIC_PRODUCT_NAME, // Product name
  title: process.env.NEXT_PUBLIC_SITE_TITLE, // Website title
  description: process.env.NEXT_PUBLIC_SITE_DESCRIPTION,  // Website description
  url: process.env.NEXT_PUBLIC_SITE_URL,  // Website URL
  locale: process.env.NEXT_PUBLIC_DEFAULT_LOCALE, // Default locale
  theme: process.env.NEXT_PUBLIC_DEFAULT_THEME_MODE,  // Default theme mode
  themeColor: process.env.NEXT_PUBLIC_THEME_COLOR,  // Light theme color
  themeColorDark: process.env.NEXT_PUBLIC_THEME_COLOR_DARK, // Dark theme color
  production: process.env.NODE_ENV === 'production',  // Production environment
}

2. Features Configuration

Open apps/web/src/features.config.ts and modify the following settings

apps/web/src/features.config.ts

{
  enableThemeToggle: process.env.NEXT_PUBLIC_ENABLE_THEME_TOGGLE, // Enable theme toggle
  enableAccountDeletion: process.env.NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_DELETION, // Enable personal account deletion
  enableTeamDeletion: process.env.NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_DELETION, // Enable team accounts deletion
  enableTeamAccounts: process.env.NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS, // Enable team accounts feature
  enableTeamCreation: process.env.NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_CREATION, // Enable team accounts creation
  enablePersonalAccountBilling: process.env.NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING, // Enable personal account billing
  enableTeamAccountBilling: process.env.NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING, // Enable team accounts billing
  languagePriority: process.env.NEXT_PUBLIC_LANGUAGE_PRIORITY, // Language priority setting
  enableNotifications: process.env.NEXT_PUBLIC_ENABLE_NOTIFICATIONS, // Enable notifications
  realtimeNotifications: process.env.NEXT_PUBLIC_REALTIME_NOTIFICATIONS, // Enable realtime notifications
  enableVersionUpdater: process.env.NEXT_PUBLIC_ENABLE_VERSION_UPDATER // Enable version updater
}

3. Sidebar Menu Configuration

You can set up the sidebar menus for individuals and organizations if the features are enabled.

  • Open apps/web/config/personal-account-navigation.config.ts and modify the routes for personal accounts.
  • Open apps/web/config/team-account-navigation.config.ts and modify the routes for team accounts.