Documentation
supastarter for Next.jssupastarter for Next.js

Configuration

Learn how to configure your supastarter application.

supastarter is a highly flexible and customizable starter kit and allows you to configure the project to your needs. Configuration is scoped to individual packages for better isolation and maintainability.

This section will cover all configuration options and when to use them.

Config files

There package and app has its own configuration file.

Web app configuration

The main configuration file for the web application. It contains settings for internationalization, organizations, users, authentication, UI, storage, contact form, and payments.

export const config = {
	// the name of the app
	appName: "supastarter for Next.js Demo",

	// the link to the documentation app (if not defined, the documentation link will not be shown in the app)
	docsLink: process.env.NEXT_PUBLIC_DOCS_URL as string | undefined,

	// the themes that should be available in the app
	enabledThemes: ["light", "dark"],
	// the default theme
	defaultTheme: "light",

	// the saas part of the application
	saas: {
		// whether the saas part should be enabled (otherwise all routes will be redirect to the marketing page)
		enabled: true,

		// whether the sidebar layout should be used
		useSidebarLayout: true,

		// the redirect path after sign in
		redirectAfterSignIn: "/app",

		// the redirect path after logout
		redirectAfterLogout: "/auth/login",
	},

	// the marketing part of the application
	marketing: {
		// whether the marketing features should be enabled (otherwise all routes will be redirect to the saas part)
		enabled: true,
	},
} as const;

API configuration

export const config = {
	// the email address to which the contact form should be sent
	contactFormTo: process.env.CONTACT_FORM_TO_MAIL as string,
} as const;

Internationalization

export const config = {
	// Define all locales here that should be available in the app
	// You need to define a label that is shown in the language selector and a currency that should be used for pricing with this locale
	locales: {
		en: {
			label: "English",
			currency: "USD",
		},
		de: {
			label: "Deutsch",
			currency: "USD",
		},
	},
	// The default locale is used if no locale is provided
	defaultLocale: "en",
	// The default currency is used for pricing if no currency is provided
	defaultCurrency: "USD",
	// The name of the cookie that is used to determine the locale
	localeCookieName: "NEXT_LOCALE",
} as const;

Auth

export const config = {
	// Whether signup is enabled
	enableSignup: true,

	// Whether magic link is enabled
	enableMagicLink: true,

	// Whether social login is enabled
	enableSocialLogin: true,

	// Whether passkeys are enabled
	enablePasskeys: true,

	// Whether password login is enabled
	enablePasswordLogin: true,

	// Whether two factor authentication is enabled
	enableTwoFactor: true,

	// The maximum age of the session cookie in seconds
	sessionCookieMaxAge: 60 * 60 * 24 * 30,

	// Users
	users: {
		// Whether you want the user to go through an onboarding form after signup (can be defined in the OnboardingForm.tsx)
		enableOnboarding: true,
	},

	// Organizations
	organizations: {
		// Whether organizations are enabled in general
		enable: true,

		// Whether the organization should be hidden from the user (use this for multi-tenant applications)
		hideOrganization: false,

		// Should users be able to create new organizations? Otherwise only admin users can create them
		enableUsersToCreateOrganizations: true,

		// Whether users should be required to be in an organization. This will redirect users to the organization page after sign in
		requireOrganization: false,

		// Define forbidden organization slugs. Make sure to add all paths that you define as a route after /app/... to avoid routing issues
		forbiddenOrganizationSlugs: [
			"new-organization",
			"admin",
			"settings",
			"ai-demo",
			"organization-invitation",
		],
	},
} as const;

Mail

export const config = {
	// the email address to which the mail should be sent from
	mailFrom: process.env.MAIL_FROM as string,
} as const;

Payments

export const config = {
	billingAttachedTo: "user" as "user" | "organization", // 'users' or 'organizations'
	plans: {
		// The free plan is treated differently. It will automatically be assigned if the user has no other plan.
		free: {
			isFree: true,
		},
		pro: {
			recommended: true,
			prices: [
				{
					type: "recurring",
					productId: process.env
						.NEXT_PUBLIC_PRICE_ID_PRO_MONTHLY as string,
					interval: "month",
					amount: 29,
					currency: "USD",
					seatBased: true,
					trialPeriodDays: 7,
				},
				{
					type: "recurring",
					productId: process.env
						.NEXT_PUBLIC_PRICE_ID_PRO_YEARLY as string,
					interval: "year",
					amount: 290,
					currency: "USD",
					seatBased: true,
					trialPeriodDays: 7,
				},
			],
		},
		lifetime: {
			prices: [
				{
					type: "one-time",
					productId: process.env
						.NEXT_PUBLIC_PRICE_ID_LIFETIME as string,
					amount: 799,
					currency: "USD",
				},
			],
		},
		enterprise: {
			isEnterprise: true,
		},
	},
} as const;

Storage

export const config = {
	// the bucket names to use for the storage provider
	bucketNames: {
		avatars: process.env.NEXT_PUBLIC_AVATARS_BUCKET_NAME ?? "avatars",
	},
} as const;

Use cases

The configuration options enable you to set up lots of different use cases. Here are some examples:

Deploy marketing page only

If you want to deploy the marketing page only, you can set the ui.saas.enabled option to false. This will disable the saas part of the application and redirect requests to the marketing page.

export const config = {
    // ...
    ui: {
        saas: {
            enabled: false,
        },
    },
};

To not have to manually set this option while developing locally, you can define an environment variable NEXT_PUBLIC_SAAS_ENABLED in your .env file and use this in the file file.

export const config = {
    // ...
    ui: {
        saas: {
            enabled: process.env.NEXT_PUBLIC_SAAS_ENABLED === "true",
        },
    },
};

This way you can set the deployed version to false while enabling the development version to true.

Disable marketing page

If you want to ship the marketing page separately and just use the SaaS part of supastarter, you can simply disable the marketing part of the application. This will redirect all requests to the SaaS part or the login page if the user is not authenticated.

export const config = {
    // ...
    ui: {
        marketing: {
            enabled: false,
        },
    },
};

Multi-tenant application

If you want to use supastarter as a multi-tenant application, you can use the following configuration. This will

  1. require users to be in an organization
  2. hide the organization from the user
  3. redirect users to the organization page after sign in
export const config = {
    // ...
    organizations: {
        hideOrganization: true,
        requireOrganization: true,
        enableUsersToCreateOrganizations: false,
    },
};

With this setup, you can have two different behaviors for creating organizations.

  1. Users can create an initial organizations (and no further)
  2. Only admins can create organizations

To enable the second behavior, you can set the auth.enableSignup option to false. This way users can only join if they are invited to an organization and organizations can only be created by admins.

export const config = {
    // ...
    auth: {
        enableSignup: false,
    },
};

Enable/disable onboarding

There is a prepared onboarding form, which allows users to set up their profile after sign up. If you want to disable it, you can set the users.enableOnboarding option to false.

export const config = {
    // ...
    users: {
        enableOnboarding: false,
    },
};

Attach billing to users or organizations

You can attach billing to users or organizations. To enable this for either one, you can set the enableBilling option to true.

export const config = {
    // for users
    users: {
        enableBilling: true,
    },
    // for organizations
    organizations: {
        enableBilling: true,
    },
};

In theory, you can have both enabled at the same time, but for most use cases you want to attach it to only one of them.

Disable organizations

If you don't want to use organizations, you can set the organizations.enable option to false. This will disable the organizations feature totally.

export const config = {
    // ...
    organizations: {
        enable: false,
    },
};

Customize authentication

You can easily (de)activate authentication methods like social login, passkeys, password login and magic links.

export const config = {
    // ...
    auth: {
        enableSocialLogin: false,
        enablePasskeys: false,
        enablePasswordLogin: false,
        enableMagicLink: false,
    },
};