env

Type-safe environment variable provider.

📦 Overview

What it does

This library allows for typechecking environment variables or secrets which are consumed by the applications. This uses t3-oss/t3-env, with type validation using Zod. These variables can be imported with full type safety by any apps or libraries.

Key Features

• Provides full type-safety to environment variables
• Helps easily detect missing or invalid environment variables
• Improves security by providing access to specific variables for certain library/app

How to use

Basic Usage Example

Assuming environment variables in the .env.example files are set in a .env file, they can be imported & consumed:

import { envWebsiteDb } from '@cuhacking/env'
 
export default defineConfig({
  // ...
  dbCredentials: {
    url: envWebsiteDb.DATABASE_URL,
  },
})

envWebsiteDb.DATABASE_URL will have type-safety up to its configurations. Based on the following configurations:

export const envWebsiteDb = createEnv({
  // ...
  server: {
    DATABASE_URL: z.string().url().startsWith('postgres'),
  },
})

The library would throw an error if the environment variable:

1. Is missing (or is not defined in the correct directory)
2. Is not a string
3. Is not a URL
4. Does not start with 'postgres'

📖 API Reference

envWebsiteDb

• Properties
  • DATABASE_URL: string: PostgreSQL database connection string.

envWebsiteServer

• Properties
  • AUTH_SECRET: string: Lucia server-side authentication secret
  • AUTH_GOOGLE_ID: string: Google authentication crendential ID
  • AUTH_GOOGLE_SECRET: string: Google authentication credential secret

Any environment variables that should be shared with all other set of variables should be placed in shared.ts

Error Handling

When using an environment variable through this library, your IDE should pick up type mismatches because of type-safety ✨

🛠️ Commands

View all commands

To view all commands from the library's project.json, package.json and inheritted:

pnpm nx show project env

Focus library usage

To view/focus on all the apps & libraries which use this library:

pnpm nx graph --focus env

📝 Contributing

Best Practices

Code Formatting

The directories of the environment variables definitions are named after the apps they represent. For example, the environment variables for website are found in env/src/website. To add a new environment variable, create a .ts file representing the set of environment variables for the certain portion of the app/library.

The library should be linted without any errors:

pnpm nx run env:lint

Testing

To run tests for this library:

pnpm nx run env:test

❓ FAQs

What happens if I don't declare new environment variables in the library?

The library will not pick up any additional environment variables thrown in the environment variables files. Therefore, it is best practice to begin by declaring the expected variable with its types in the library, and then providing it in the .env file. Afterwards, don't forget to include an example (not your own key) in the respected .env.example file.

Can I just use process.env.<VAR_NAME>?

There are many reasons why we specifically use this wrapper library. Those were mentioned above, and for that reason, using process.env should be the last option.

🛑 Troubleshooting

Common Errors

Invalid environment variable(s)

Invalid environment variables should be picked up either in build-time or run-time. An error code of the sort means that the environment variable is either missing, or not in the correct directory:

❌ Invalid environment variables: { DATABASE_URL: [ 'Required' ] }

How cool this is? The kindest type of error you can get! 😁