Best practices for configuring Metorial with the AI SDK in your projects.

Setting Up Environment Variables

Create a .env file in your project root:

# .env
METORIAL_API_KEY=your-metorial-api-key
METORIAL_DEPLOYMENT_ID=your-server-deployment-id

# AI Provider Keys
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key

Loading Environment Variables

Node.js with dotenv

import 'dotenv/config';
import { Metorial } from 'metorial';

const metorial = new Metorial({
  apiKey: process.env.METORIAL_API_KEY
});

Next.js

Next.js automatically loads .env.local files:

// app/api/chat/route.ts
import { Metorial } from 'metorial';

export async function POST(req: Request) {
  const metorial = new Metorial({
    apiKey: process.env.METORIAL_API_KEY
  });
  
  // Your AI SDK code
}

Configuration Helper

Create a configuration module for reusable settings:

// config/metorial.ts
import { Metorial } from 'metorial';

if (!process.env.METORIAL_API_KEY) {
  throw new Error('METORIAL_API_KEY is required');
}

export const metorial = new Metorial({
  apiKey: process.env.METORIAL_API_KEY
});

export const defaultDeployment = process.env.METORIAL_DEPLOYMENT_ID;

Then use it throughout your application:

import { metorial, defaultDeployment } from './config/metorial';
import { metorialAiSdk } from '@metorial/ai-sdk';

await metorial.withProviderSession(
  metorialAiSdk,
  { serverDeployments: [defaultDeployment] },
  async session => {
    // Your code
  }
);

Different Environments

Use different deployment IDs for different environments:

# .env.development
METORIAL_DEPLOYMENT_ID=dev-deployment-id

# .env.production
METORIAL_DEPLOYMENT_ID=prod-deployment-id

Security Best Practices

1. Never commit .env files: Add to .gitignore:

   .env
   .env.local
   .env.*.local
   

2. Use different keys per environment: Separate API keys for development, staging, and production

3. Validate environment variables: Check for required variables at startup

4. Use secrets management: For production, use services like AWS Secrets Manager, HashiCorp Vault, or your platform's secrets management

Example Validation

// config/validate.ts
const requiredEnvVars = [
  'METORIAL_API_KEY',
  'METORIAL_DEPLOYMENT_ID'
];

for (const envVar of requiredEnvVars) {
  if (!process.env[envVar]) {
    throw new Error(`Missing required environment variable: ${envVar}`);
  }
}

With proper configuration, your Metorial integration will be secure, maintainable, and easy to deploy across different environments.