@platformatic/foundation 3.63.0-alpha.3 → 3.64.0

package/index.d.ts

@@ -78,13 +78,24 @@ export interface ValidationError {
 export type ConfigurationOptions<T = {}> = Partial<{
   validate: boolean
   validationOptions: object
-  transform: (config: Configuration<T>) => Promise<Configuration<T>> | Configuration<T>
+  // Read directly off the context by every capability package (astro, basic,
+  // next, node, service, ...) to pick a development/production code path.
+  isProduction: boolean
+  // loadConfiguration() always invokes the caller-supplied transform hook
+  // with all three arguments (config, schema, options), mirroring the
+  // exported transform() function's own parameter list.
+  transform: (
+    config: Configuration<T>,
+    schema: object,
+    options: ConfigurationOptions<T>
+  ) => Promise<Configuration<T>> | Configuration<T>
   upgrade: (logger: Logger, config: RawConfiguration, version: string) => Promise<RawConfiguration> | RawConfiguration
   env: Record<string, string>
   ignoreProcessEnv: boolean
   replaceEnv: boolean
   replaceEnvIgnore: string[]
   onMissingEnv: (key: string) => string | undefined
+  strictEnv: boolean | 'warn'
   fixPaths: boolean
   logger: Logger
   root: string
@@ -154,9 +165,13 @@ export declare function replaceEnv (
   onMissingEnv?: (key: string) => string | undefined,
   ignore?: string[]
 ): RawConfiguration
+// `config` also accepts an array: the exported `applications` schema is a
+// JSONSchemaType<object[]> (an ARRAY schema), and validate() is called with
+// a matching array of application configs before they are handed to
+// prepareApplication()/addApplications().
 export declare function validate (
   schema: JSONSchemaType<any>,
-  config: RawConfiguration,
+  config: RawConfiguration | RawConfiguration[],
   validationOptions?: object,
   fixPaths?: boolean,
   root?: string
@@ -166,7 +181,22 @@ export declare function loadConfiguration (
   schema?: any,
   options?: ConfigurationOptions
 ): Promise<Configuration>
-export declare function loadConfigurationModule (root: string, config: RawConfiguration | ModuleWithVersion): any
+
+// The capability module object returned by loadConfigurationModule(): the
+// object a capability exports (its shape is otherwise capability-defined,
+// hence the index signature).
+export interface ConfigurationModule {
+  loadConfiguration?: (configPath: string) => Promise<unknown>
+  skipTelemetryHooks?: boolean
+  createCommands?: (applicationId: string) => unknown
+  modulesToLoad?: string[]
+  [key: string]: unknown
+}
+export declare function loadConfigurationModule (
+  root: string,
+  config: RawConfiguration | ModuleWithVersion,
+  pkg?: string
+): Promise<ConfigurationModule>
 
 // Error types
 export declare const ERROR_PREFIX: string
@@ -181,6 +211,7 @@ export declare const SourceMissingError: FastifyError
 export declare const RootMissingError: FastifyError
 export declare const SchemaMustBeDefinedError: FastifyError
 export declare const ConfigurationDoesNotValidateAgainstSchemaError: FastifyError
+export declare const MissingEnvVariablesError: FastifyError
 
 // Execution types
 export declare function executeWithTimeout<T> (promise: Promise<T>, timeout: number, timeoutValue?: any): Promise<T>

package/lib/configuration.js

@@ -12,6 +12,7 @@ import {
   CannotParseConfigFileError,
   ConfigurationDoesNotValidateAgainstSchemaError,
   InvalidConfigFileExtensionError,
+  MissingEnvVariablesError,
   RootMissingError,
   SourceMissingError
 } from './errors.js'
@@ -382,10 +383,13 @@ export async function loadEnv (root, ignoreProcessEnv = false, additionalEnv = {
   const baseEnv = ignoreProcessEnv ? {} : process.env
   const envFromFile = envFile ? parseEnv(await readFile(envFile, 'utf-8')) : {}
 
+  // The env file provides fallback defaults: variables already set in the real
+  // environment (and explicit programmatic values) take precedence over it,
+  // matching the dotenv/docker-compose/Vite convention.
   return {
+    ...envFromFile,
     ...baseEnv,
-    ...additionalEnv,
-    ...envFromFile
+    ...additionalEnv
   }
 }
 
@@ -442,6 +446,16 @@ export function replaceEnv (config, env, onMissingEnv, ignore) {
   return config
 }
 
+function normalizeStrictEnv (value) {
+  if (value === 'warn') {
+    return 'warn'
+  } else if (value === 'false' || value === '') {
+    return false
+  }
+
+  return Boolean(value)
+}
+
 export async function loadConfiguration (source, schema, options = {}) {
   const {
     validate: shouldValidate,
@@ -453,6 +467,7 @@ export async function loadConfiguration (source, schema, options = {}) {
     replaceEnv: shouldReplaceEnv,
     replaceEnvIgnore,
     onMissingEnv,
+    strictEnv: strictEnvOption,
     fixPaths,
     logger,
     skipMetadata,
@@ -487,7 +502,42 @@ export async function loadConfiguration (source, schema, options = {}) {
   env.PLT_ROOT = root
 
   if (shouldReplaceEnv) {
-    config = replaceEnv(config, env, onMissingEnv, replaceEnvIgnore)
+    const missingEnv = new Set()
+
+    config = replaceEnv(
+      config,
+      env,
+      key => {
+        const value = onMissingEnv?.(key)
+
+        if (typeof value === 'undefined' || value === null) {
+          missingEnv.add(key)
+        }
+
+        return value
+      },
+      replaceEnvIgnore
+    )
+
+    // strictEnv can be set programmatically or in the configuration file itself, either at the top level
+    // (runtime configurations) or in the runtime property (capabilities configurations).
+    const strictEnv = normalizeStrictEnv(strictEnvOption ?? config.strictEnv ?? config.runtime?.strictEnv)
+
+    if (strictEnv && missingEnv.size > 0) {
+      const keys = Array.from(missingEnv).sort().join(', ')
+
+      if (strictEnv === 'warn') {
+        const message = `The configuration references the following environment variables which are not set: ${keys}`
+
+        if (logger) {
+          logger.warn(message)
+        } else {
+          process.emitWarning(message)
+        }
+      } else {
+        throw new MissingEnvVariablesError(keys)
+      }
+    }
   }
 
   const moduleInfo = extractModuleFromSchemaUrl(config)

package/lib/errors.js

@@ -56,3 +56,7 @@ export const ConfigurationDoesNotValidateAgainstSchemaError = createError(
   `${ERROR_PREFIX}_CONFIGURATION_DOES_NOT_VALIDATE_AGAINST_SCHEMA`,
   'The configuration does not validate against the configuration schema'
 )
+export const MissingEnvVariablesError = createError(
+  `${ERROR_PREFIX}_MISSING_ENV_VARIABLES`,
+  'The configuration references the following environment variables which are not set: %s'
+)

package/lib/module.js

@@ -17,6 +17,11 @@ export const applicationTypes = [
   { name: '@platformatic/next', label: 'Next.js', dependencies: ['next'] },
   { name: '@platformatic/remix', label: 'Remix', dependencies: ['@remix-run/dev'] },
   { name: '@platformatic/astro', label: 'Astro', dependencies: ['astro'] },
+  { name: '@platformatic/react-router', label: 'React Router', dependencies: ['@react-router/dev'] },
+  { name: '@platformatic/nuxt', label: 'Nuxt', dependencies: ['nuxt'] },
+  { name: '@platformatic/tanstack', label: 'TanStack Start', dependencies: ['@tanstack/react-start'] },
+  // Nitro applications often use Vite, so Nitro must be checked first.
+  { name: '@platformatic/nitro', label: 'Nitro', dependencies: ['nitro', 'nitropack'] },
   // Since Vite is often used with other frameworks, we must check for Vite last amongst frontend frameworks
   { name: '@platformatic/vite', label: 'Vite', dependencies: ['vite'] },
   {

package/lib/schema.js

@@ -396,7 +396,8 @@ export const server = {
     portAssignment: {
       type: 'string',
       enum: ['shared', 'perWorkerIncrement'],
-      description: 'Configures how entrypoint server worker ports are assigned. When set to shared, all workers listen on the same port. When set to perWorkerIncrement, each worker will use its own port, starting from port (worker 0).'
+      description:
+        'Configures how entrypoint server worker ports are assigned. When set to shared, all workers listen on the same port. When set to perWorkerIncrement, each worker will use its own port, starting from port (worker 0).'
     },
     backlog: {
       type: 'integer',
@@ -595,6 +596,18 @@ export const fastifyServer = {
         }
       }
     },
+    ajv: {
+      type: 'object',
+      description:
+        'Options for the Fastify request-validation Ajv instance (the Fastify `ajv` server option). Only `customOptions` is configurable from the config file; for example set `customOptions.coerceTypes` to `false` to reject empty strings on fields that allow the `null` type instead of coercing them to `null`.',
+      properties: {
+        customOptions: {
+          type: 'object',
+          additionalProperties: true
+        }
+      },
+      additionalProperties: false
+    },
     caseSensitive: {
       type: 'boolean'
     },
@@ -791,7 +804,8 @@ export const telemetry = {
           type: 'string'
         }
       ],
-      description: 'Enable the OpenTelemetry diagnostic logger. Diagnostic messages are forwarded to the Platformatic global logger using the current logger level.'
+      description:
+        'Enable the OpenTelemetry diagnostic logger. Diagnostic messages are forwarded to the Platformatic global logger using the current logger level.'
     }
   },
   required: ['applicationName'],
@@ -1125,7 +1139,7 @@ export const runtimeProperties = {
           },
           { type: 'string' }
         ],
-        default: 10000
+        default: 30000
       },
       application: {
         anyOf: [
@@ -1533,6 +1547,11 @@ export const runtimeProperties = {
   envfile: {
     type: 'string'
   },
+  strictEnv: {
+    anyOf: [{ type: 'boolean' }, { type: 'string' }],
+    description:
+      'When set to true, the configuration loading fails if a {PLT_*} placeholder references an environment variable which is not set. When set to "warn", a warning listing the missing variables is logged but the placeholders are still replaced with an empty string. Defaults to false.'
+  },
   sourceMaps: {
     type: 'boolean',
     default: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/foundation",
-  "version": "3.63.0-alpha.3",
+  "version": "3.64.0",
   "description": "Platformatic Foundation",
   "main": "index.js",
   "types": "index.d.ts",
@@ -37,7 +37,7 @@
     "c8": "^11.0.0",
     "cleaner-spec-reporter": "^0.5.0",
     "eslint": "9",
-    "fastify": "^5.7.0",
+    "fastify": "^5.0.0",
     "neostandard": "^0.12.0",
     "pino": "^9.9.0",
     "pino-test": "^1.0.1",