Skip to main content

configure

The configure function is used to set up global configuration for your Nadle build. This reference covers all available options and their usage.

Basic Usage​

import { configure } from "nadle";

configure({
	projectName: "my-project",
	workspaceRoot: process.cwd(),
	logLevel: "info"
});

Configuration Options​

Core Options​

projectName​

  • Type: string
  • Default: Package name from package.json
  • Description: The name of your project
configure({
	projectName: "my-awesome-project"
});

workspaceRoot​

  • Type: string
  • Default: process.cwd()
  • Description: The root directory of your project
configure({
	workspaceRoot: "/path/to/project"
});

logLevel​

  • Type: 'error' | 'warn' | 'info' | 'debug'
  • Default: 'info'
  • Description: The default logging level
configure({
	logLevel: "debug"
});

Execution Options​

parallel​

  • Type: boolean | number
  • Default: true
  • Description: Enable parallel task execution or set max parallel tasks
configure({
	parallel: 4 // Run up to 4 tasks in parallel
});

plugins​

  • Type: Plugin[]
  • Default: []
  • Description: List of Nadle plugins to use
import { TypeScriptPlugin } from "@nadle/typescript";

configure({
	plugins: [
		new TypeScriptPlugin({
			tsconfig: "tsconfig.json"
		})
	]
});

Environment Options​

environment​

  • Type: Record<string, string>
  • Default: {}
  • Description: Global environment variables
configure({
	environment: {
		NODE_ENV: "development",
		API_URL: "http://localhost:3000"
	}
});

environmentFiles​

  • Type: string[]
  • Default: ['.env', '.env.local']
  • Description: List of environment files to load
configure({
	environmentFiles: [".env", ".env.local", ".env.${env}"]
});

Advanced Options​

hooks​

  • Type: BuildHooks
  • Description: Build lifecycle hooks
configure({
	hooks: {
		beforeTask: async (taskName) => {
			console.log(`Starting task: ${taskName}`);
		},
		afterTask: async (taskName, success) => {
			console.log(`Task ${taskName} finished: ${success}`);
		}
	}
});

cache​

  • Type: CacheOptions
  • Description: Task caching configuration
configure({
	cache: {
		enabled: true,
		directory: ".nadle-cache"
	}
});

Type Definitions​

ConfigureOptions​

interface ConfigureOptions {
	projectName?: string;
	workspaceRoot?: string;
	logLevel?: LogLevel;
	parallel?: boolean | number;
	plugins?: Plugin[];
	environment?: Record<string, string>;
	environmentFiles?: string[];
	hooks?: BuildHooks;
	cache?: CacheOptions;
}

LogLevel​

type LogLevel = "error" | "warn" | "info" | "debug";

BuildHooks​

interface BuildHooks {
	beforeTask?: (taskName: string) => Promise<void>;
	afterTask?: (taskName: string, success: boolean) => Promise<void>;
	beforeBuild?: () => Promise<void>;
	afterBuild?: (success: boolean) => Promise<void>;
}

CacheOptions​

interface CacheOptions {
	enabled?: boolean;
	directory?: string;
	ttl?: number;
}

Examples​

Basic Configuration​

configure({
	projectName: "my-project",
	logLevel: "info",
	parallel: true
});

With Plugins and Environment​

import { TypeScriptPlugin } from "@nadle/typescript";
import { DockerPlugin } from "@nadle/docker";

configure({
	projectName: "my-project",
	plugins: [new TypeScriptPlugin(), new DockerPlugin()],
	environment: {
		NODE_ENV: "development"
	}
});

With Hooks​

configure({
	hooks: {
		beforeTask: async (taskName) => {
			console.log(`Starting: ${taskName}`);
		},
		afterTask: async (taskName, success) => {
			console.log(`Finished ${taskName}: ${success}`);
		},
		beforeBuild: async () => {
			console.log("Build starting");
		},
		afterBuild: async (success) => {
			console.log(`Build finished: ${success}`);
		}
	}
});

With Caching​

configure({
	cache: {
		enabled: true,
		directory: ".nadle-cache",
		ttl: 3600 // 1 hour
	}
});

tasks.register

The tasks.register function is used to define tasks in your Nadle build. This reference covers all aspects of task registration and configuration.

Basic Usage​

import { tasks } from "nadle";

tasks
	.register("taskName", async ({ logger }) => {
		logger.info("Task running...");
	})
	.config({
		description: "Task description"
	});

Task Registration​

Simple Task​

tasks.register("build", async () => {
	// Task implementation
});

Task with Context​

tasks.register("build", async ({ logger, options, env }) => {
	logger.info("Building...");
	const nodeEnv = env.NODE_ENV;
	// Implementation
});

Task with Options​

interface BuildOptions {
	target: "web" | "mobile";
	optimize: boolean;
}

tasks
	.register("build", async ({ options }) => {
		const { target, optimize } = options;
		// Implementation
	})
	.config<BuildOptions>({
		defaultOptions: {
			target: "web",
			optimize: false
		}
	});

Task Context​

Available Properties​

PropertyTypeDescription
loggerLoggerTask logger
optionsTTask options
envRecord<string, string>Environment variables
workspaceWorkspaceWorkspace utilities
runTaskRunnerTask runner

Logger​

tasks.register("build", async ({ logger }) => {
	logger.debug("Debug message");
	logger.info("Info message");
	logger.warn("Warning message");
	logger.error("Error message");
	logger.success("Success message");
	logger.progress(0.5, "Half way there");
});

Options​

interface DeployOptions {
	environment: "staging" | "production";
	region?: string;
}

tasks
	.register("deploy", async ({ options }) => {
		const { environment, region = "us-east-1" } = options;
		// Implementation
	})
	.config<DeployOptions>({
		defaultOptions: {
			environment: "staging"
		}
	});

Environment Variables​

tasks.register("build", async ({ env }) => {
	const nodeEnv = env.NODE_ENV;
	const apiUrl = env.API_URL;
	// Implementation
});

Workspace Utilities​

tasks.register("build", async ({ workspace }) => {
	const srcDir = workspace.resolve("src");
	const exists = await workspace.exists("package.json");
	const files = await workspace.glob("src/**/*.ts");
	// Implementation
});

Task Runner​

tasks.register("build:all", async ({ run }) => {
	// Run tasks in sequence
	await run("clean");
	await run("compile");

	// Run tasks in parallel
	await Promise.all([run("test"), run("lint")]);
});

Task Configuration​

Configuration Options​

OptionTypeDescription
descriptionstringTask description
groupstringTask group
dependsOnstring[]Required dependencies
optionalDependsOnstring[]Optional dependencies
environmentRecord<string, string>Task environment
parallelbooleanEnable parallel execution
defaultOptionsTDefault task options

Basic Configuration​

tasks
	.register("build", async () => {
		// Implementation
	})
	.config({
		description: "Build the project",
		group: "Build",
		dependsOn: ["clean"]
	});

Dependencies​

tasks
	.register("deploy", async () => {
		// Implementation
	})
	.config({
		dependsOn: ["build", "test"], // Required
		optionalDependsOn: ["lint"] // Optional
	});

Environment Variables​

tasks
	.register("deploy", async () => {
		// Implementation
	})
	.config({
		environment: {
			NODE_ENV: "production",
			DEPLOY_TARGET: "staging"
		}
	});

Special Task Types​

Watch Tasks​

tasks.register("watch", async () => {
	return {
		paths: ["src/**/*.ts"],
		ignore: ["**/*.test.ts"],
		onChange: async (changes) => {
			await tasks.run("build");
		}
	};
});

Custom Task Types​

interface CopyTaskOptions {
	source: string;
	destination: string;
}

const CopyTask = {
	run: async ({ options, logger }) => {
		const { source, destination } = options;
		logger.info(`Copying ${source} to ${destination}`);
		// Implementation
	}
};

tasks.register("copy", CopyTask).config<CopyTaskOptions>({
	defaultOptions: {
		source: "src",
		destination: "dist"
	}
});

Type Definitions​

TaskContext​

interface TaskContext<T = any> {
	logger: Logger;
	options: T;
	env: Record<string, string>;
	workspace: Workspace;
	run: TaskRunner;
}

TaskConfig​

interface TaskConfig<T = any> {
	description?: string;
	group?: string;
	dependsOn?: string[];
	optionalDependsOn?: string[];
	environment?: Record<string, string>;
	parallel?: boolean;
	defaultOptions?: T;
}

WatchOptions​

interface WatchOptions {
	paths: string[];
	ignore?: string[];
	onChange: (changes: string[]) => Promise<void>;
}

Examples​

Complete Task Example​

interface BuildOptions {
	target: "web" | "mobile";
	optimize: boolean;
	outDir?: string;
}

tasks
	.register("build", async ({ logger, options, env, workspace, run }) => {
		const { target, optimize, outDir = "dist" } = options;
		const nodeEnv = env.NODE_ENV;

		logger.info(`Building ${target} for ${nodeEnv}`);

		// Clean first
		await run("clean");

		// Build implementation
		logger.progress(0.5, "Compiling...");

		if (optimize) {
			logger.info("Optimizing build...");
		}

		const outputPath = workspace.resolve(outDir);
		// More implementation...

		logger.success("Build complete");
	})
	.config<BuildOptions>({
		description: "Build the project",
		group: "Build",
		dependsOn: ["clean"],
		environment: {
			NODE_ENV: "production"
		},
		defaultOptions: {
			target: "web",
			optimize: false
		}
	});