1import{_ as i,o as a,i as n,ak as l}from"./chunks/framework.CIfHljvi.js";const g=JSON.parse('{"title":"Aliases Support","description":"","frontmatter":{},"headers":[],"relativePath":"features/aliases.md","filePath":"features/aliases.md","lastUpdated":1758415309000}'),e={name:"features/aliases.md"};function t(h,s,p,k,r,o){return a(),n("div",null,[...s[0]||(s[0]=[l(`<h1 id="aliases-support" tabindex="-1">Aliases Support <a class="header-anchor" href="#aliases-support" aria-label="Permalink to "Aliases Support"">â</a></h1><p>bunfig provides powerful alias support that allows you to maintain backward compatibility when renaming configurations or provide fallback configuration names.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to "Overview"">â</a></h2><p>Aliases are alternative configuration names that bunfig will check when the primary configuration name doesn't exist. This feature is particularly useful for:</p><ul><li><strong>Backward compatibility</strong> when renaming tools or configurations</li><li><strong>Multiple naming conventions</strong> for the same configuration</li><li><strong>Gradual migration</strong> from old configuration names to new ones</li><li><strong>Fallback configurations</strong> for different environments</li></ul><h2 id="basic-usage" tabindex="-1">Basic Usage <a class="header-anchor" href="#basic-usage" aria-label="Permalink to "Basic Usage"">â</a></h2><p>To use aliases, simply provide an <code>alias</code> property in your configuration options:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { loadConfig } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> 'bunfig'</span></span> 2<span class="line"></span> 3<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> config</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> loadConfig</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span> 4<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'my-new-tool'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 5<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> alias: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'my-old-tool'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Fallback name</span></span> 6<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> defaultConfig: {</span></span> 7<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> port: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">3000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 8<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> host: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'localhost'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 9<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span> 10<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span></span></code></pre></div><h2 id="search-order" tabindex="-1">Search Order <a class="header-anchor" href="#search-order" aria-label="Permalink to "Search Order"">â</a></h2><p>When you specify an alias, bunfig searches for configuration files in this order:</p><ol><li><strong>Primary name files</strong> (<code>my-new-tool.*</code>)</li><li><strong>Primary name with alias suffix</strong> (<code>my-new-tool.my-old-tool.*</code>)</li><li><strong>Alias name files</strong> (<code>my-old-tool.*</code>)</li></ol><p>This applies to all search locations:</p><ul><li>Project directories (<code>./</code>, <code>./config</code>, <code>./.config</code>)</li><li>Home directory (<code>~/.config/</code>)</li><li>Package.json sections</li></ul><h3 id="example-search-pattern" tabindex="-1">Example Search Pattern <a class="header-anchor" href="#example-search-pattern" aria-label="Permalink to "Example Search Pattern"">â</a></h3><p>With <code>name: 'tlsx'</code> and <code>alias: 'tls'</code>, bunfig will look for:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span>
10<pre class="shiki shiki-themes github-light github-dark vp-code" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0"><code><span class="line"><span>Project directories:</span></span> 11<span class="line"><span>âââ tlsx.config.ts (primary name)</span></span> 12<span class="line"><span>âââ .tlsx.config.ts</span></span> 13<span class="line"><span>âââ tlsx.ts</span></span> 14<span class="line"><span>âââ .tlsx.ts</span></span> 15<span class="line"><span>âââ tlsx.tls.config.ts (primary.alias pattern)</span></span> 16<span class="line"><span>âââ .tlsx.tls.config.ts</span></span> 17<span class="line"><span>âââ tls.config.ts (alias name)</span></span> 18<span class="line"><span>âââ .tls.config.ts</span></span> 19<span class="line"><span>âââ tls.ts</span></span> 20<span class="line"><span>âââ .tls.ts</span></span> 21<span class="line"><span></span></span> 22<span class="line"><span>Home directory:</span></span> 23<span class="line"><span>âââ ~/.config/tlsx/config.ts</span></span> 24<span class="line"><span>âââ ~/.config/tlsx/tlsx.config.ts</span></span> 25<span class="line"><span>âââ ~/.config/tlsx/tls.config.ts (alias in primary dir)</span></span> 26<span class="line"><span>âââ ~/.config/tls/config.ts (alias directory)</span></span> 27<span class="line"><span>âââ ~/.config/tls/tls.config.ts</span></span> 28<span class="line"><span>âââ ~/.config/tls/tlsx.config.ts (primary in alias dir)</span></span> 29<span class="line"><span></span></span> 30<span class="line"><span>Package.json:</span></span> 31<span class="line"><span>âââ "tlsx": { ... } (primary section)</span></span> 32<span class="line"><span>âââ "tls": { ... } (alias section)</span></span></code></pre></div><h2 id="real-world-examples" tabindex="-1">Real-World Examples <a class="header-anchor" href="#real-world-examples" aria-label="Permalink to "Real-World Examples"">â</a></h2><h3 id="tool-renaming" tabindex="-1">Tool Renaming <a class="header-anchor" href="#tool-renaming" aria-label="Permalink to "Tool Renaming"">â</a></h3><p>When renaming a tool from <code>webpack-config</code> to <code>bundler</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> config</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> loadConfig</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span> 33<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'bundler'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 34<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> alias: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'webpack-config'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 35<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> defaultConfig: {</span></span> 36<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> entry: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'./src/index.ts'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 37<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> output: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'./dist'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 38<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span> 39<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span></span></code></pre></div><p>This allows users to gradually migrate from <code>webpack-config.js</code> to <code>bundler.config.js</code> without breaking existing setups.</p><h3 id="framework-migration" tabindex="-1">Framework Migration <a class="header-anchor" href="#framework-migration" aria-label="Permalink to "Framework Migration"">â</a></h3><p>When migrating from one framework to another:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span>
39<pre class="shiki shiki-themes github-light github-dark vp-code" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> config</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> loadConfig</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span> 40<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'vite-config'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 41<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> alias: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'webpack-config'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 42<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> defaultConfig: {</span></span> 43<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> build: {</span></span> 44<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> target: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'es2020'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 45<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> minify: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 46<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span> 47<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span> 48<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span></span></code></pre></div><h3 id="environment-specific-fallbacks" tabindex="-1">Environment-Specific Fallbacks <a class="header-anchor" href="#environment-specific-fallbacks" aria-label="Permalink to "Environment-Specific Fallbacks"">â</a></h3><p>Using aliases for environment-specific configurations:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> config</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> loadConfig</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span> 49<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name: process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">NODE_ENV</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> 'production'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ?</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> 'prod-config'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> :</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> 'dev-config'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 50<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> alias: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'base-config'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Fallback to base configuration</span></span> 51<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> defaultConfig: {</span></span> 52<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> apiUrl: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'http://localhost:3000'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 53<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> debug: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">
53false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 54<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span> 55<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span></span></code></pre></div><h2 id="multiple-aliases" tabindex="-1">Multiple Aliases <a class="header-anchor" href="#multiple-aliases" aria-label="Permalink to "Multiple Aliases"">â</a></h2><p>While bunfig currently supports a single alias, you can implement multiple fallbacks using a wrapper function:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> loadConfigWithMultipleAliases</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"><</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">T</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">>(</span></span> 56<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> name</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 57<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> aliases</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[],</span></span> 58<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> defaultConfig</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> T</span></span> 59<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span> 60<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> alias</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> of</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">undefined</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">...</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">aliases]) {</span></span> 61<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> try</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span> 62<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> loadConfig</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span> 63<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name,</span></span> 64<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> alias,</span></span> 65<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> defaultConfig,</span></span> 66<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> })</span></span> 67<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span> 68<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> catch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (error) {</span></span> 69<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Continue to next alias</span></span> 70<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (alias </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> aliases[aliases.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">length</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> -</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]) {</span></span> 71<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> throw</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> error </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">
71// Rethrow if last alias also fails</span></span> 72<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span> 73<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span> 74<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span> 75<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span> 76<span class="line"></span> 77<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Usage</span></span> 78<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> config</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> loadConfigWithMultipleAliases</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span> 79<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> 'new-tool'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 80<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'legacy-tool'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'old-tool'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'deprecated-tool'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span> 81<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { port: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">3000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span> 82<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span></code></pre></div><h2 id="package-json-aliases" tabindex="-1">Package.json Aliases <a class="header-anchor" href="#package-json-aliases" aria-label="Permalink to "Package.json Aliases"">â</a></h2><p>Aliases also work with package.json sections:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span> 83<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "name"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"my-project"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 84<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "new-tool"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span> 85<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "port"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">4000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 86<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "host"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"0.0.0.0"</span></span> 87<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span> 88<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "old-tool"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span> 89<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "port"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">3000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 90<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "host"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"localhost"</span></span> 91<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span> 92<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span>
92<pre class="shiki shiki-themes github-light github-dark vp-code" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> config</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> loadConfig</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span> 93<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'new-tool'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 94<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> alias: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'old-tool'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 95<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> defaultConfig: { port: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">8080</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span> 96<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span></span> 97<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Will use "new-tool" section if present, otherwise "old-tool"</span></span></code></pre></div><h2 id="home-directory-aliases" tabindex="-1">Home Directory Aliases <a class="header-anchor" href="#home-directory-aliases" aria-label="Permalink to "Home Directory Aliases"">â</a></h2><p>Aliases work seamlessly with home directory configurations:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Primary configuration</span></span> 98<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">~</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">
98/.config/new-tool/config.ts</span></span> 99<span class="line"></span> 100<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Alias configuration (fallback)</span></span> 101<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">~</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">/.config/old-tool/config.ts</span></span></code></pre></div><p>Both directories are checked, with the primary name taking precedence.</p><h2 id="best-practices" tabindex="-1">Best Practices <a class="header-anchor" href="#best-practices" aria-label="Permalink to "Best Practices"">â</a></h2><h3 id="_1-use-descriptive-aliases" tabindex="-1">1. Use Descriptive Aliases <a class="header-anchor" href="#_1-use-descriptive-aliases" aria-label="Permalink to "1. Use Descriptive Aliases"">â</a></h3><p>Choose aliases that clearly indicate their purpose:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Good</span></span> 102<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> config1</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span> 103<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'bundler-v2'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 104<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> alias: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'bundler-v1'</span></span> 105<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span> 106<span class="line"></span> 107<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Better</span></span> 108<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> config2</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span> 109<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'esbuild-config'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 110<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> alias: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'webpack-config'</span></span> 111<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="_2-document-migration-paths" tabindex="-1">2. Document Migration Paths <a class="header-anchor" href="#_2-document-migration-paths" aria-label="Permalink to "2. Document Migration Paths"">â</a></h3><p>When using aliases for migration, document the transition:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">/**</span></span> 112<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> * Configuration loader with backward compatibility.</span></span> 113<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> *</span></span> 114<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> * Migration path: 'legacy-config' â 'modern-config'</span></span> 115<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> * Support for 'legacy-config' will be removed in v3.0</span></span> 116<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> */</span></span> 117<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> config</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> loadConfig</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">
117({</span></span> 118<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'modern-config'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 119<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> alias: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'legacy-config'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 120<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> defaultConfig: { </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">/* ... */</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span> 121<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span></span></code></pre></div><h3 id="_3-version-aware-aliases" tabindex="-1">3. Version-Aware Aliases <a class="header-anchor" href="#_3-version-aware-aliases" aria-label="Permalink to "3. Version-Aware Aliases"">â</a></h3><p>Consider version-specific aliases:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> config</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> loadConfig</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span> 122<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`my-tool-v\${</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">MAJOR_VERSION</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 123<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> alias: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`my-tool-v\${</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">MAJOR_VERSION</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> -</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 1</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 124<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> defaultConfig: { </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">/* ... */</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span> 125<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span></span></code></pre></div><h3 id="_4-gradual-deprecation" tabindex="-1">4. Gradual Deprecation <a class="header-anchor" href="#_4-gradual-deprecation" aria-label="Permalink to "4. Gradual Deprecation"">â</a></h3><p>Use aliases to gradually deprecate old configuration names:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Phase 1: Introduce new name with alias support</span></span> 126<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> config</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> loadConfig</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">
126({</span></span> 127<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'new-name'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 128<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> alias: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'old-name'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 129<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> defaultConfig: { </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">/* ... */</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span> 130<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span></span> 131<span class="line"></span> 132<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Phase 2: Warn about deprecated usage</span></span> 133<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> config</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> loadConfig</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span> 134<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'new-name'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 135<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> alias: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'old-name'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 136<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> defaultConfig: { </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">/* ... */</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span> 137<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span></span> 138<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Add deprecation warning if old-name config is found</span></span> 139<span class="line"></span> 140<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Phase 3: Remove alias support</span></span> 141<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> config</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> loadConfig</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span> 142<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'new-name'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span> 143<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // alias removed</span></span> 144<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> defaultConfig: { </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">/* ... */</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span> 145<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span></span></code></pre></div><h2 id="troubleshooting" tabindex="-1">Troubleshooting <a class="header-anchor" href="#troubleshooting" aria-label="Permalink to "Troubleshooting"">â</a></h2><h3 id="configuration-not-found" tabindex="-1">Configuration Not Found <a class="header-anchor" href="#configuration-not-found" aria-label="Permalink to "Configuration Not Found"">â</a></h3><p>If neither the primary name nor alias resolves to a configuration:</p><ol><li>
145Check that both configuration names are spelled correctly</li><li>Verify file permissions in all search directories</li><li>Ensure configuration files are properly formatted</li><li>Use debug logging to see which files are being checked</li></ol><h3 id="unexpected-configuration" tabindex="-1">Unexpected Configuration <a class="header-anchor" href="#unexpected-configuration" aria-label="Permalink to "Unexpected Configuration"">â</a></h3><p>If the wrong configuration is being loaded:</p><ol><li>Remember that primary name takes precedence over alias</li><li>Check all search locations for conflicting configurations</li><li>Verify the search order matches your expectations</li><li>Use verbose logging to trace the resolution process</li></ol><h3 id="alias-conflicts" tabindex="-1">Alias Conflicts <a class="header-anchor" href="#alias-conflicts" aria-label="Permalink to "Alias Conflicts"">â</a></h3><p>When multiple aliases might conflict:</p><ol><li>Use unique, descriptive names</li><li>Avoid circular alias references</li><li>Consider namespace prefixes for related configurations</li><li>Document your alias strategy clearly</li></ol><h2 id="related-features" tabindex="-1">Related Features <a class="header-anchor" href="#related-features" aria-label="Permalink to "Related Features"">â</a></h2><ul><li><a href="./configuration-loading">Configuration Loading</a> - Complete configuration resolution process</li><li><a href="./home-directory">Home Directory Support</a> - Global configuration management</li><li><a href="./multiple-formats">Multiple Formats</a> - Supported configuration file formats</li></ul>`,63)])])}const E=i(e,[["render",t]]);export{g as __pageData,E as default};
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.