@granite-js/plugin-core 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @granite-js/plugin-core
 
+## 0.1.11
+
+### Patch Changes
+
+- d3a2b58: improve resolver plugin
+  - @granite-js/utils@0.1.11
+
+## 0.1.10
+
+### Patch Changes
+
+- 9438be5: add dynamic config support
+  - @granite-js/utils@0.1.10
+
 ## 0.1.9
 
 ### Patch Changes

package/dist/index.cjs

@@ -22,7 +22,12 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 //#endregion
 const es_toolkit = __toESM(require("es-toolkit"));
+const path = __toESM(require("path"));
+const __granite_js_utils = __toESM(require("@granite-js/utils"));
+const fs = __toESM(require("fs"));
 const zod = __toESM(require("zod"));
+const cosmiconfig = __toESM(require("cosmiconfig"));
+const cosmiconfig_typescript_loader = __toESM(require("cosmiconfig-typescript-loader"));
 
 //#region src/createContext.ts
 function createContext() {
@@ -319,6 +324,35 @@ function createPluginContext() {
 	return context;
 }
 
+//#endregion
+//#region src/utils/buildResult.ts
+function isBuildSuccess(result) {
+	return "bundle" in result;
+}
+function isBuildFailure(result) {
+	return !("bundle" in result);
+}
+
+//#endregion
+//#region src/config/graniteGlobals.ts
+function prepareGraniteGlobalsScript(config) {
+	const filePath = writeGraniteGlobalsScript(config);
+	return {
+		esbuild: { prelude: [filePath] },
+		metro: { serializer: { getPolyfills: () => [filePath] } }
+	};
+}
+function writeGraniteGlobalsScript(config) {
+	const script = getGraniteGlobalScript(config);
+	const filePath = path.default.join((0, __granite_js_utils.getLocalTempDirectoryPath)(config.rootDir), "granite-globals.js");
+	(0, __granite_js_utils.prepareLocalDirectory)(config.rootDir);
+	fs.default.writeFileSync(filePath, script, "utf-8");
+	return filePath;
+}
+function getGraniteGlobalScript({ appName, scheme }) {
+	return ["global.__granite = global.__granite || {};", `global.__granite.app = { name: ${JSON.stringify(appName)}, scheme: ${JSON.stringify(scheme)} };`].join("\n");
+}
+
 //#endregion
 //#region src/schema/pluginConfig.ts
 const pluginConfigSchema = zod.object({
@@ -333,11 +367,130 @@ const pluginConfigSchema = zod.object({
 	plugins: zod.custom()
 });
 
+//#endregion
+//#region src/config/defineConfig.ts
+/**
+* @public
+* @category Configuration
+* @name defineConfig
+* @description
+* Configures your Granite application by defining key settings in `granite.config.ts`.
+*
+* The configuration lets you specify:
+* - How users will access your app through a URL scheme (e.g. `granite://`)
+* - Your app's unique name that appears in the URL (e.g. `granite://my-service`)
+* - Build settings for bundlers like ESBuild and Metro
+* - Code transformation settings through Babel
+* - Additional functionality through Granite plugins
+*
+* @param config - Configuration options
+* @param config.cwd - Working directory for build process (defaults to process.cwd())
+* @param config.appName - Your app's unique identifier
+* @param config.scheme - URL scheme for launching your app (e.g. 'granite')
+* @param config.outdir - Where to output build files (defaults to 'dist')
+* @param config.entryFile - Your app's entry point (defaults to './src/_app.tsx')
+* @param config.build - Customize build settings
+* @param config.metro - Configure Metro bundler settings
+* @param config.devServer - Configure Mpack dev server settings
+* @param config.plugins - Granite plugins to enhance functionality
+* @returns The processed configuration
+*
+* @example
+* Here's a basic configuration that:
+* - Makes your app accessible via the `granite://` scheme
+* - Names your service "my-app" so it's reachable at `granite://my-app`
+* - Uses the Hermes plugin to optimize JavaScript bundles into bytecode
+*
+* ```ts
+* import { defineConfig } from '@granite-js/react-native/config';
+* import { hermes } from '@granite-js/plugin-hermes';
+*
+* export default defineConfig({
+*   // The name of your microservice
+*   appName: 'my-app',
+*   // The URL scheme for deep linking
+*   scheme: 'granite',
+*   // Entry file path
+*   entryFile: 'index.ts',
+*   // Array of plugins to use
+*   plugins: [hermes()],
+* });
+* ```
+*/
+const defineConfig = async (config) => {
+	const parsed = pluginConfigSchema.parse(config);
+	const cwd = parsed.cwd ?? (0, __granite_js_utils.getPackageRoot)();
+	const appName = parsed.appName;
+	const scheme = parsed.scheme;
+	const entryFile = path.default.resolve(cwd, parsed.entryFile);
+	const outdir = path.default.join(cwd, parsed.outdir);
+	const parsedBuildConfig = parsed.build;
+	const parsedDevServerConfig = parsed.devServer;
+	const parsedMetroConfig = parsed.metro;
+	const parsedConfig = {
+		...parsedBuildConfig,
+		devServer: parsedDevServerConfig,
+		metro: parsedMetroConfig
+	};
+	const { configs, pluginHooks } = await resolvePlugins(parsed.plugins);
+	const globalsScriptConfig = prepareGraniteGlobalsScript({
+		rootDir: cwd,
+		appName,
+		scheme
+	});
+	const mergedConfig = mergeConfig(parsedConfig, ...[globalsScriptConfig, ...configs].filter(es_toolkit.isNotNil));
+	const { metro, devServer,...build } = mergedConfig ?? {};
+	return {
+		cwd,
+		appName,
+		entryFile,
+		outdir,
+		build,
+		devServer,
+		pluginHooks,
+		metro: {
+			...metro,
+			babelConfig: mergedConfig?.babel,
+			transformSync: mergedConfig?.transformer?.transformSync
+		}
+	};
+};
+
+//#endregion
+//#region src/config/loadConfig.ts
+const MODULE_NAME = "granite";
+const loadConfig = async (options = {}) => {
+	let result;
+	if (options.configFile) result = await getConfigExplorer().load(path.default.resolve(options.root ?? (0, __granite_js_utils.getPackageRoot)(), options.configFile));
+	else result = await getConfigExplorer({ searchPlaces: [
+		`${MODULE_NAME}.config.ts`,
+		`${MODULE_NAME}.config.mts`,
+		`${MODULE_NAME}.config.js`,
+		`${MODULE_NAME}.config.cjs`
+	] }).search(options.root);
+	(0, es_toolkit.assert)(result, "Config file not found");
+	const config = await result.config;
+	return config;
+};
+function getConfigExplorer(options) {
+	return (0, cosmiconfig.cosmiconfig)(MODULE_NAME, {
+		loaders: {
+			".ts": (0, cosmiconfig_typescript_loader.TypeScriptLoader)(),
+			".mts": (0, cosmiconfig_typescript_loader.TypeScriptLoader)()
+		},
+		...options
+	});
+}
+
 //#endregion
 exports.createContext = createContext;
 exports.createPluginContext = createPluginContext;
 exports.createPluginHooksDriver = createPluginHooksDriver;
+exports.defineConfig = defineConfig;
 exports.flattenPlugins = flattenPlugins;
+exports.isBuildFailure = isBuildFailure;
+exports.isBuildSuccess = isBuildSuccess;
+exports.loadConfig = loadConfig;
 exports.mergeBuildConfigs = mergeBuildConfigs;
 exports.mergeConfig = mergeConfig;
 exports.pluginConfigSchema = pluginConfigSchema;

package/dist/index.d.cts

@@ -5,6 +5,7 @@ import { HandleFunction } from "connect";
 import { FastifyPluginAsync, FastifyPluginCallback } from "fastify";
 import * as babel from "@babel/core";
 import * as z from "zod";
+import { BuildFailureResult as BuildFailureResult$1, BuildResult as BuildResult$1, BuildSuccessResult as BuildSuccessResult$1 } from "@granite-js/plugin-core";
 
 //#region src/types/BuildConfig.d.ts
 interface BuildConfig {
@@ -84,7 +85,7 @@ interface ResolverConfig {
    */
   protocols?: ProtocolConfig;
 }
-interface AliasConfig {
+interface AliasConfig extends Pick<esbuild$1.ResolveOptions, 'importer' | 'kind' | 'resolveDir' | 'with'> {
   /**
    * Replacement target module path
    */
@@ -92,10 +93,7 @@ interface AliasConfig {
   /**
    * Replacement module path or function that returns module path
    */
-  to: string | ((context: {
-    args: esbuild$1.OnResolveArgs;
-    resolve: esbuild$1.PluginBuild['resolve'];
-  }) => string | Promise<string>);
+  to: ResolveResult | AliasResolver;
   /**
    * - `false`: (default) replace even if subpath exists (`^name(?:$|/)`)
    * - `true`: replace only if the target is exactly matched (`^name$`)
@@ -123,6 +121,14 @@ interface AliasConfig {
    */
   exact?: boolean;
 }
+type ResolveResult = string | ResolveResultWithOptions;
+interface ResolveResultWithOptions extends Omit<esbuild$1.ResolveOptions, 'pluginName' | 'pluginData'> {
+  path: string;
+}
+type AliasResolver = (context: {
+  args: esbuild$1.OnResolveArgs;
+  resolve: esbuild$1.PluginBuild['resolve'];
+}) => ResolveResult | Promise<ResolveResult>;
 /**
  * Custom protocol resolve configuration
  *
@@ -201,7 +207,8 @@ interface BabelConfig {
   plugins?: (string | [string, any])[];
 } //#endregion
 //#region src/types/BuildResult.d.ts
-interface BuildResult extends esbuild.BuildResult {
+type BuildResult = BuildSuccessResult | BuildFailureResult;
+interface BuildSuccessResult extends esbuild.BuildResult {
   bundle: BundleData;
   outfile: BuildConfig['outfile'];
   sourcemapOutfile: NonNullable<BuildConfig['sourcemapOutfile']>;
@@ -211,6 +218,11 @@ interface BuildResult extends esbuild.BuildResult {
   duration: number;
   size: number;
 }
+interface BuildFailureResult extends esbuild.BuildResult {
+  platform: BuildConfig['platform'];
+  extra: BuildConfig['extra'];
+  duration: number;
+}
 interface BundleData {
   source: esbuild.OutputFile;
   sourcemap: esbuild.OutputFile;
@@ -592,4 +604,80 @@ declare function createPluginHooksDriver(config: CompleteGraniteConfig): {
 declare function createPluginContext(): PluginContext;
 
 //#endregion
-export { AdditionalMetroConfig, AliasConfig, BabelConfig, BuildConfig, BuildResult, BundleData, CompleteGraniteConfig, DevServerConfig, EsbuildConfig, GraniteConfig, GranitePlugin, GranitePluginBuildPostHandler, GranitePluginBuildPreHandler, GranitePluginConfig, GranitePluginCore, GranitePluginDevHandlerArgs, GranitePluginDevPostHandler, GranitePluginDevPreHandler, GranitePluginHooks, GranitePluginPostHandlerArgs, GranitePluginPreHandlerArgs, MetroDevServerConfig, MetroMiddleware, Middleware, ParsedGraniteConfig, PluginBuildConfig, PluginConfig, PluginContext, PluginInput, PluginMetroConfig, PluginResolvable, ProtocolConfig, ResolverConfig, SwcConfig, TransformAsync, TransformSync, TransformerConfig, createContext, createPluginContext, createPluginHooksDriver, flattenPlugins, mergeBuildConfigs, mergeConfig, pluginConfigSchema, resolvePlugins };
+//#region src/utils/buildResult.d.ts
+declare function isBuildSuccess(result: BuildResult$1): result is BuildSuccessResult$1;
+declare function isBuildFailure(result: BuildResult$1): result is BuildFailureResult$1;
+
+//#endregion
+//#region src/config/defineConfig.d.ts
+/**
+ * @public
+ * @category Configuration
+ * @name defineConfig
+ * @description
+ * Configures your Granite application by defining key settings in `granite.config.ts`.
+ *
+ * The configuration lets you specify:
+ * - How users will access your app through a URL scheme (e.g. `granite://`)
+ * - Your app's unique name that appears in the URL (e.g. `granite://my-service`)
+ * - Build settings for bundlers like ESBuild and Metro
+ * - Code transformation settings through Babel
+ * - Additional functionality through Granite plugins
+ *
+ * @param config - Configuration options
+ * @param config.cwd - Working directory for build process (defaults to process.cwd())
+ * @param config.appName - Your app's unique identifier
+ * @param config.scheme - URL scheme for launching your app (e.g. 'granite')
+ * @param config.outdir - Where to output build files (defaults to 'dist')
+ * @param config.entryFile - Your app's entry point (defaults to './src/_app.tsx')
+ * @param config.build - Customize build settings
+ * @param config.metro - Configure Metro bundler settings
+ * @param config.devServer - Configure Mpack dev server settings
+ * @param config.plugins - Granite plugins to enhance functionality
+ * @returns The processed configuration
+ *
+ * @example
+ * Here's a basic configuration that:
+ * - Makes your app accessible via the `granite://` scheme
+ * - Names your service "my-app" so it's reachable at `granite://my-app`
+ * - Uses the Hermes plugin to optimize JavaScript bundles into bytecode
+ *
+ * ```ts
+ * import { defineConfig } from '@granite-js/react-native/config';
+ * import { hermes } from '@granite-js/plugin-hermes';
+ *
+ * export default defineConfig({
+ *   // The name of your microservice
+ *   appName: 'my-app',
+ *   // The URL scheme for deep linking
+ *   scheme: 'granite',
+ *   // Entry file path
+ *   entryFile: 'index.ts',
+ *   // Array of plugins to use
+ *   plugins: [hermes()],
+ * });
+ * ```
+ */
+declare const defineConfig: (config: GraniteConfig) => Promise<CompleteGraniteConfig>;
+
+//#endregion
+//#region src/config/loadConfig.d.ts
+interface LoadConfigOptions {
+  /**
+   * Root directory to search for the config file.
+   *
+   * Defaults to project root
+   */
+  root?: string;
+  /**
+   * Exact path to the config file.
+   *
+   * If provided, the config file will be loaded from the given path.
+   * Otherwise, the config file will be searched for in the root directory.
+   */
+  configFile?: string;
+}
+declare const loadConfig: (options?: LoadConfigOptions) => Promise<CompleteGraniteConfig>;
+
+//#endregion
+export { AdditionalMetroConfig, AliasConfig, AliasResolver, BabelConfig, BuildConfig, BuildFailureResult, BuildResult, BuildSuccessResult, BundleData, CompleteGraniteConfig, DevServerConfig, EsbuildConfig, GraniteConfig, GranitePlugin, GranitePluginBuildPostHandler, GranitePluginBuildPreHandler, GranitePluginConfig, GranitePluginCore, GranitePluginDevHandlerArgs, GranitePluginDevPostHandler, GranitePluginDevPreHandler, GranitePluginHooks, GranitePluginPostHandlerArgs, GranitePluginPreHandlerArgs, MetroDevServerConfig, MetroMiddleware, Middleware, ParsedGraniteConfig, PluginBuildConfig, PluginConfig, PluginContext, PluginInput, PluginMetroConfig, PluginResolvable, ProtocolConfig, ResolveResult, ResolveResultWithOptions, ResolverConfig, SwcConfig, TransformAsync, TransformSync, TransformerConfig, createContext, createPluginContext, createPluginHooksDriver, defineConfig, flattenPlugins, isBuildFailure, isBuildSuccess, loadConfig, mergeBuildConfigs, mergeConfig, pluginConfigSchema, resolvePlugins };

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import * as esbuild from "esbuild";
 import { HandleFunction } from "connect";
 import { FastifyPluginAsync, FastifyPluginCallback } from "fastify";
 import * as babel from "@babel/core";
+import { BuildFailureResult as BuildFailureResult$1, BuildResult as BuildResult$1, BuildSuccessResult as BuildSuccessResult$1 } from "@granite-js/plugin-core";
 
 //#region src/types/BuildConfig.d.ts
 interface BuildConfig {
@@ -84,7 +85,7 @@ interface ResolverConfig {
    */
   protocols?: ProtocolConfig;
 }
-interface AliasConfig {
+interface AliasConfig extends Pick<esbuild$1.ResolveOptions, 'importer' | 'kind' | 'resolveDir' | 'with'> {
   /**
    * Replacement target module path
    */
@@ -92,10 +93,7 @@ interface AliasConfig {
   /**
    * Replacement module path or function that returns module path
    */
-  to: string | ((context: {
-    args: esbuild$1.OnResolveArgs;
-    resolve: esbuild$1.PluginBuild['resolve'];
-  }) => string | Promise<string>);
+  to: ResolveResult | AliasResolver;
   /**
    * - `false`: (default) replace even if subpath exists (`^name(?:$|/)`)
    * - `true`: replace only if the target is exactly matched (`^name$`)
@@ -123,6 +121,14 @@ interface AliasConfig {
    */
   exact?: boolean;
 }
+type ResolveResult = string | ResolveResultWithOptions;
+interface ResolveResultWithOptions extends Omit<esbuild$1.ResolveOptions, 'pluginName' | 'pluginData'> {
+  path: string;
+}
+type AliasResolver = (context: {
+  args: esbuild$1.OnResolveArgs;
+  resolve: esbuild$1.PluginBuild['resolve'];
+}) => ResolveResult | Promise<ResolveResult>;
 /**
  * Custom protocol resolve configuration
  *
@@ -201,7 +207,8 @@ interface BabelConfig {
   plugins?: (string | [string, any])[];
 } //#endregion
 //#region src/types/BuildResult.d.ts
-interface BuildResult extends esbuild.BuildResult {
+type BuildResult = BuildSuccessResult | BuildFailureResult;
+interface BuildSuccessResult extends esbuild.BuildResult {
   bundle: BundleData;
   outfile: BuildConfig['outfile'];
   sourcemapOutfile: NonNullable<BuildConfig['sourcemapOutfile']>;
@@ -211,6 +218,11 @@ interface BuildResult extends esbuild.BuildResult {
   duration: number;
   size: number;
 }
+interface BuildFailureResult extends esbuild.BuildResult {
+  platform: BuildConfig['platform'];
+  extra: BuildConfig['extra'];
+  duration: number;
+}
 interface BundleData {
   source: esbuild.OutputFile;
   sourcemap: esbuild.OutputFile;
@@ -592,4 +604,80 @@ declare function createPluginHooksDriver(config: CompleteGraniteConfig): {
 declare function createPluginContext(): PluginContext;
 
 //#endregion
-export { AdditionalMetroConfig, AliasConfig, BabelConfig, BuildConfig, BuildResult, BundleData, CompleteGraniteConfig, DevServerConfig, EsbuildConfig, GraniteConfig, GranitePlugin, GranitePluginBuildPostHandler, GranitePluginBuildPreHandler, GranitePluginConfig, GranitePluginCore, GranitePluginDevHandlerArgs, GranitePluginDevPostHandler, GranitePluginDevPreHandler, GranitePluginHooks, GranitePluginPostHandlerArgs, GranitePluginPreHandlerArgs, MetroDevServerConfig, MetroMiddleware, Middleware, ParsedGraniteConfig, PluginBuildConfig, PluginConfig, PluginContext, PluginInput, PluginMetroConfig, PluginResolvable, ProtocolConfig, ResolverConfig, SwcConfig, TransformAsync, TransformSync, TransformerConfig, createContext, createPluginContext, createPluginHooksDriver, flattenPlugins, mergeBuildConfigs, mergeConfig, pluginConfigSchema, resolvePlugins };
+//#region src/utils/buildResult.d.ts
+declare function isBuildSuccess(result: BuildResult$1): result is BuildSuccessResult$1;
+declare function isBuildFailure(result: BuildResult$1): result is BuildFailureResult$1;
+
+//#endregion
+//#region src/config/defineConfig.d.ts
+/**
+ * @public
+ * @category Configuration
+ * @name defineConfig
+ * @description
+ * Configures your Granite application by defining key settings in `granite.config.ts`.
+ *
+ * The configuration lets you specify:
+ * - How users will access your app through a URL scheme (e.g. `granite://`)
+ * - Your app's unique name that appears in the URL (e.g. `granite://my-service`)
+ * - Build settings for bundlers like ESBuild and Metro
+ * - Code transformation settings through Babel
+ * - Additional functionality through Granite plugins
+ *
+ * @param config - Configuration options
+ * @param config.cwd - Working directory for build process (defaults to process.cwd())
+ * @param config.appName - Your app's unique identifier
+ * @param config.scheme - URL scheme for launching your app (e.g. 'granite')
+ * @param config.outdir - Where to output build files (defaults to 'dist')
+ * @param config.entryFile - Your app's entry point (defaults to './src/_app.tsx')
+ * @param config.build - Customize build settings
+ * @param config.metro - Configure Metro bundler settings
+ * @param config.devServer - Configure Mpack dev server settings
+ * @param config.plugins - Granite plugins to enhance functionality
+ * @returns The processed configuration
+ *
+ * @example
+ * Here's a basic configuration that:
+ * - Makes your app accessible via the `granite://` scheme
+ * - Names your service "my-app" so it's reachable at `granite://my-app`
+ * - Uses the Hermes plugin to optimize JavaScript bundles into bytecode
+ *
+ * ```ts
+ * import { defineConfig } from '@granite-js/react-native/config';
+ * import { hermes } from '@granite-js/plugin-hermes';
+ *
+ * export default defineConfig({
+ *   // The name of your microservice
+ *   appName: 'my-app',
+ *   // The URL scheme for deep linking
+ *   scheme: 'granite',
+ *   // Entry file path
+ *   entryFile: 'index.ts',
+ *   // Array of plugins to use
+ *   plugins: [hermes()],
+ * });
+ * ```
+ */
+declare const defineConfig: (config: GraniteConfig) => Promise<CompleteGraniteConfig>;
+
+//#endregion
+//#region src/config/loadConfig.d.ts
+interface LoadConfigOptions {
+  /**
+   * Root directory to search for the config file.
+   *
+   * Defaults to project root
+   */
+  root?: string;
+  /**
+   * Exact path to the config file.
+   *
+   * If provided, the config file will be loaded from the given path.
+   * Otherwise, the config file will be searched for in the root directory.
+   */
+  configFile?: string;
+}
+declare const loadConfig: (options?: LoadConfigOptions) => Promise<CompleteGraniteConfig>;
+
+//#endregion
+export { AdditionalMetroConfig, AliasConfig, AliasResolver, BabelConfig, BuildConfig, BuildFailureResult, BuildResult, BuildSuccessResult, BundleData, CompleteGraniteConfig, DevServerConfig, EsbuildConfig, GraniteConfig, GranitePlugin, GranitePluginBuildPostHandler, GranitePluginBuildPreHandler, GranitePluginConfig, GranitePluginCore, GranitePluginDevHandlerArgs, GranitePluginDevPostHandler, GranitePluginDevPreHandler, GranitePluginHooks, GranitePluginPostHandlerArgs, GranitePluginPreHandlerArgs, MetroDevServerConfig, MetroMiddleware, Middleware, ParsedGraniteConfig, PluginBuildConfig, PluginConfig, PluginContext, PluginInput, PluginMetroConfig, PluginResolvable, ProtocolConfig, ResolveResult, ResolveResultWithOptions, ResolverConfig, SwcConfig, TransformAsync, TransformSync, TransformerConfig, createContext, createPluginContext, createPluginHooksDriver, defineConfig, flattenPlugins, isBuildFailure, isBuildSuccess, loadConfig, mergeBuildConfigs, mergeConfig, pluginConfigSchema, resolvePlugins };

package/dist/index.js

@@ -1,5 +1,10 @@
-import { isNotNil } from "es-toolkit";
+import { assert, isNotNil } from "es-toolkit";
+import path from "path";
+import { getLocalTempDirectoryPath, getPackageRoot, prepareLocalDirectory } from "@granite-js/utils";
+import fs from "fs";
 import * as z from "zod";
+import { cosmiconfig } from "cosmiconfig";
+import { TypeScriptLoader } from "cosmiconfig-typescript-loader";
 
 //#region src/createContext.ts
 function createContext() {
@@ -296,6 +301,35 @@ function createPluginContext() {
 	return context;
 }
 
+//#endregion
+//#region src/utils/buildResult.ts
+function isBuildSuccess(result) {
+	return "bundle" in result;
+}
+function isBuildFailure(result) {
+	return !("bundle" in result);
+}
+
+//#endregion
+//#region src/config/graniteGlobals.ts
+function prepareGraniteGlobalsScript(config) {
+	const filePath = writeGraniteGlobalsScript(config);
+	return {
+		esbuild: { prelude: [filePath] },
+		metro: { serializer: { getPolyfills: () => [filePath] } }
+	};
+}
+function writeGraniteGlobalsScript(config) {
+	const script = getGraniteGlobalScript(config);
+	const filePath = path.join(getLocalTempDirectoryPath(config.rootDir), "granite-globals.js");
+	prepareLocalDirectory(config.rootDir);
+	fs.writeFileSync(filePath, script, "utf-8");
+	return filePath;
+}
+function getGraniteGlobalScript({ appName, scheme }) {
+	return ["global.__granite = global.__granite || {};", `global.__granite.app = { name: ${JSON.stringify(appName)}, scheme: ${JSON.stringify(scheme)} };`].join("\n");
+}
+
 //#endregion
 //#region src/schema/pluginConfig.ts
 const pluginConfigSchema = z.object({
@@ -311,4 +345,119 @@ const pluginConfigSchema = z.object({
 });
 
 //#endregion
-export { createContext, createPluginContext, createPluginHooksDriver, flattenPlugins, mergeBuildConfigs, mergeConfig, pluginConfigSchema, resolvePlugins };
+//#region src/config/defineConfig.ts
+/**
+* @public
+* @category Configuration
+* @name defineConfig
+* @description
+* Configures your Granite application by defining key settings in `granite.config.ts`.
+*
+* The configuration lets you specify:
+* - How users will access your app through a URL scheme (e.g. `granite://`)
+* - Your app's unique name that appears in the URL (e.g. `granite://my-service`)
+* - Build settings for bundlers like ESBuild and Metro
+* - Code transformation settings through Babel
+* - Additional functionality through Granite plugins
+*
+* @param config - Configuration options
+* @param config.cwd - Working directory for build process (defaults to process.cwd())
+* @param config.appName - Your app's unique identifier
+* @param config.scheme - URL scheme for launching your app (e.g. 'granite')
+* @param config.outdir - Where to output build files (defaults to 'dist')
+* @param config.entryFile - Your app's entry point (defaults to './src/_app.tsx')
+* @param config.build - Customize build settings
+* @param config.metro - Configure Metro bundler settings
+* @param config.devServer - Configure Mpack dev server settings
+* @param config.plugins - Granite plugins to enhance functionality
+* @returns The processed configuration
+*
+* @example
+* Here's a basic configuration that:
+* - Makes your app accessible via the `granite://` scheme
+* - Names your service "my-app" so it's reachable at `granite://my-app`
+* - Uses the Hermes plugin to optimize JavaScript bundles into bytecode
+*
+* ```ts
+* import { defineConfig } from '@granite-js/react-native/config';
+* import { hermes } from '@granite-js/plugin-hermes';
+*
+* export default defineConfig({
+*   // The name of your microservice
+*   appName: 'my-app',
+*   // The URL scheme for deep linking
+*   scheme: 'granite',
+*   // Entry file path
+*   entryFile: 'index.ts',
+*   // Array of plugins to use
+*   plugins: [hermes()],
+* });
+* ```
+*/
+const defineConfig = async (config) => {
+	const parsed = pluginConfigSchema.parse(config);
+	const cwd = parsed.cwd ?? getPackageRoot();
+	const appName = parsed.appName;
+	const scheme = parsed.scheme;
+	const entryFile = path.resolve(cwd, parsed.entryFile);
+	const outdir = path.join(cwd, parsed.outdir);
+	const parsedBuildConfig = parsed.build;
+	const parsedDevServerConfig = parsed.devServer;
+	const parsedMetroConfig = parsed.metro;
+	const parsedConfig = {
+		...parsedBuildConfig,
+		devServer: parsedDevServerConfig,
+		metro: parsedMetroConfig
+	};
+	const { configs, pluginHooks } = await resolvePlugins(parsed.plugins);
+	const globalsScriptConfig = prepareGraniteGlobalsScript({
+		rootDir: cwd,
+		appName,
+		scheme
+	});
+	const mergedConfig = mergeConfig(parsedConfig, ...[globalsScriptConfig, ...configs].filter(isNotNil));
+	const { metro, devServer,...build } = mergedConfig ?? {};
+	return {
+		cwd,
+		appName,
+		entryFile,
+		outdir,
+		build,
+		devServer,
+		pluginHooks,
+		metro: {
+			...metro,
+			babelConfig: mergedConfig?.babel,
+			transformSync: mergedConfig?.transformer?.transformSync
+		}
+	};
+};
+
+//#endregion
+//#region src/config/loadConfig.ts
+const MODULE_NAME = "granite";
+const loadConfig = async (options = {}) => {
+	let result;
+	if (options.configFile) result = await getConfigExplorer().load(path.resolve(options.root ?? getPackageRoot(), options.configFile));
+	else result = await getConfigExplorer({ searchPlaces: [
+		`${MODULE_NAME}.config.ts`,
+		`${MODULE_NAME}.config.mts`,
+		`${MODULE_NAME}.config.js`,
+		`${MODULE_NAME}.config.cjs`
+	] }).search(options.root);
+	assert(result, "Config file not found");
+	const config = await result.config;
+	return config;
+};
+function getConfigExplorer(options) {
+	return cosmiconfig(MODULE_NAME, {
+		loaders: {
+			".ts": TypeScriptLoader(),
+			".mts": TypeScriptLoader()
+		},
+		...options
+	});
+}
+
+//#endregion
+export { createContext, createPluginContext, createPluginHooksDriver, defineConfig, flattenPlugins, isBuildFailure, isBuildSuccess, loadConfig, mergeBuildConfigs, mergeConfig, pluginConfigSchema, resolvePlugins };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@granite-js/plugin-core",
   "type": "module",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "The core plugin module for Granite",
   "scripts": {
     "prepack": "yarn build",
@@ -31,9 +31,12 @@
     "vitest": "^3.0.9"
   },
   "dependencies": {
+    "@granite-js/utils": "0.1.11",
     "@swc/core": "1.5.24",
     "@types/babel__core": "^7",
     "@types/connect": "^3",
+    "cosmiconfig": "^9.0.0",
+    "cosmiconfig-typescript-loader": "^5.1.0",
     "es-toolkit": "^1.39.8",
     "esbuild": "^0.25.8",
     "fastify": "4.14.0",