### Install @shellicar/build-version

Source: https://github.com/shellicar/build-version/blob/main/packages/build-version/README.md

Commands to install the build plugin package using common Node.js package managers.

```bash
npm i --save @shellicar/build-version
```

```bash
pnpm add @shellicar/build-version
```

--------------------------------

### Install @shellicar/build-version

Source: https://context7.com/shellicar/build-version/llms.txt

Installs the @shellicar/build-version package using npm or pnpm. This is the initial step to integrate the build version plugin into your project.

```bash
npm i --save @shellicar/build-version
# or
pnpm add @shellicar/build-version
```

--------------------------------

### Configure and Import Version Plugin

Source: https://github.com/shellicar/build-version/blob/main/README.md

Demonstrates how to register the plugin in a Vite configuration file and import the generated version module into the application code.

```typescript
// vite.config.ts
import VersionPlugin from '@shellicar/build-version/vite'

export default defineConfig({
  plugins: [
    VersionPlugin({})
  ]
})
```

```typescript
// main.ts
import version from '@shellicar/build-version/version'
console.log(version)
```

--------------------------------

### Configure Environment-Aware Build Settings

Source: https://context7.com/shellicar/build-version/llms.txt

Demonstrates how to conditionally configure the plugin based on the current environment, such as toggling debug modes or switching between Git and GitVersion calculators. Includes a helper function for safely accessing version metadata in the application.

```typescript
import VersionPlugin from '@shellicar/build-version/vite';
import type { Options } from '@shellicar/build-version/types';
import { defineConfig } from 'vite';
import version from '@shellicar/build-version/version';

const versionCalculator = process.env.CI ? 'git' : 'gitversion';

const options: Options = {
  debug: !process.env.CI,
  versionCalculator,
  strict: Boolean(process.env.CI),
};

export default defineConfig({
  plugins: [VersionPlugin(options)],
});

function displayVersion() {
  if (!version.version) {
    console.warn('Version information not available');
    return 'unknown';
  }
  return `v${version.version} (${version.shortSha})`;
}
```

--------------------------------

### Configure Vite Plugin

Source: https://github.com/shellicar/build-version/blob/main/packages/build-version/README.md

Integrate the plugin into the Vite configuration file to enable version calculation during the build process.

```typescript
import VersionPlugin from '@shellicar/build-version/vite'

export default defineConfig({
  plugins: [
    VersionPlugin({})
  ]
})
```

--------------------------------

### Configure Version Calculation Strategies

Source: https://context7.com/shellicar/build-version/llms.txt

Select between built-in Git calculation or the external GitVersion CLI tool to determine project versioning based on repository state.

```typescript
// Configuration using Git calculator
import VersionPlugin from '@shellicar/build-version/vite';

export default defineConfig({
  plugins: [
    VersionPlugin({
      versionCalculator: 'git',
    }),
  ],
});
```

```typescript
// Configuration using GitVersion
import VersionPlugin from '@shellicar/build-version/vite';

export default defineConfig({
  plugins: [
    VersionPlugin({
      versionCalculator: 'gitversion',
      strict: true,
    }),
  ],
});
```

--------------------------------

### esbuild Integration with @shellicar/build-version

Source: https://context7.com/shellicar/build-version/llms.txt

Demonstrates integrating the @shellicar/build-version plugin with esbuild's programmatic API. It shows how to configure the plugin options and include it in the esbuild build process, and how to import and use version information in the application code.

```typescript
// build.mts
import versionPlugin from '@shellicar/build-version/esbuild';
import type { Options } from '@shellicar/build-version/types';
import { build } from 'esbuild';

const options: Options = {
  versionCalculator: 'git',
  debug: true,
  strict: Boolean(process.env.CI),
};

build({
  entryPoints: ['src/main.ts'],
  outdir: 'dist',
  bundle: true,
  platform: 'node',
  target: 'node20',
  plugins: [versionPlugin(options)],
});

// src/main.ts
import version from '@shellicar/build-version/version';

export const main = () => {
  console.log('Version Info:', version);
};

main();
```

--------------------------------

### Define Custom Version Calculator

Source: https://github.com/shellicar/build-version/blob/main/README.md

Shows how to provide a custom function to the plugin to override default version calculation logic.

```typescript
VersionPlugin({
  versionCalculator: () => '1.0.0-custom'
})
```

--------------------------------

### Version Information Interface

Source: https://github.com/shellicar/build-version/blob/main/README.md

The structure of the version object exposed by the virtual module.

```typescript
interface VersionInfo {
  buildDate: string;
  branch: string;
  sha: string;
  shortSha: string;
  commitDate: string;
  version: string;
}
```

--------------------------------

### Integrate Build Version Plugin with Build Tools

Source: https://context7.com/shellicar/build-version/llms.txt

Configure the build version plugin within various bundlers and build tools. Each integration requires importing the specific adapter and providing options for version calculation.

```typescript
// tsup.config.ts
import versionPlugin from '@shellicar/build-version/esbuild';
import type { Options } from '@shellicar/build-version/types';
import { defineConfig } from 'tsup';

const pluginOptions: Options = {
  debug: true,
  strict: true,
  versionCalculator: 'git',
};

export default defineConfig(() => ({
  bundle: true,
  entry: ['src/main.ts'],
  esbuildPlugins: [versionPlugin(pluginOptions)],
  format: ['esm'],
  outDir: 'dist',
  target: 'node22',
}));
```

```javascript
// rollup.config.js
import VersionPlugin from '@shellicar/build-version/rollup';

export default {
  input: 'src/main.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm',
  },
  plugins: [
    VersionPlugin({
      versionCalculator: 'git',
      debug: false,
    }),
  ],
};
```

```javascript
// rspack.config.js
import VersionPlugin from '@shellicar/build-version/rspack';

export default {
  entry: './src/index.js',
  plugins: [
    VersionPlugin({
      versionCalculator: 'gitversion',
      strict: true,
    }),
  ],
};
```

```typescript
// farm.config.ts
import VersionPlugin from '@shellicar/build-version/farm';

export default {
  plugins: [
    VersionPlugin({
      versionCalculator: 'git',
      debug: false,
    }),
  ],
};
```

--------------------------------

### Plugin Options Configuration

Source: https://context7.com/shellicar/build-version/llms.txt

Defines the TypeScript interface for configuring the @shellicar/build-version plugin. Options include selecting the version calculator strategy, enabling debug logging, and setting strict error handling.

```typescript
interface Options {
  /**
   * Version calculator configuration
   * @default 'gitversion'
   */
  versionCalculator?: 'gitversion' | 'git' | (() => { version: string; branch: string });

  /**
   * Enable debug logging
   * @default false
   */
  debug?: boolean;

  /**
   * When true, errors will be thrown if versioning fails
   * When false, errors will be logged and empty values will be returned
   * @default false
   */
  strict?: boolean;
}
```

--------------------------------

### Integrate Build Version with Frameworks

Source: https://context7.com/shellicar/build-version/llms.txt

Configure the plugin for framework-specific environments like Nuxt and Astro to expose version data to the frontend.

```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@shellicar/build-version/nuxt'],
  buildVersion: {
    versionCalculator: 'git',
    debug: true,
    strict: false,
  },
});
```

```javascript
// astro.config.mjs
import VersionPlugin from '@shellicar/build-version/astro';
import { defineConfig } from 'astro/config';

export default defineConfig({
  integrations: [
    VersionPlugin({
      versionCalculator: 'git',
      debug: true,
    }),
  ],
});
```

--------------------------------

### Import Version Module

Source: https://github.com/shellicar/build-version/blob/main/packages/build-version/README.md

Access the calculated version information in your application code by importing it from the virtual module.

```typescript
import version from '@shellicar/build-version/version'
```

--------------------------------

### Vite Integration with @shellicar/build-version

Source: https://context7.com/shellicar/build-version/llms.txt

Configures the @shellicar/build-version plugin within a Vite project. It demonstrates how to import the plugin, set options, and access version information in the application's main entry point.

```typescript
// vite.config.ts
import VersionPlugin from '@shellicar/build-version/vite';
import type { Options } from '@shellicar/build-version/types';
import { defineConfig } from 'vite';

const options: Options = {
  debug: true,
  versionCalculator: 'git',  // Use pure Git commands
  strict: Boolean(process.env.CI),  // Strict mode in CI
};

export default defineConfig({
  plugins: [VersionPlugin(options)],
});

// main.ts - Import version info in your application
import version from '@shellicar/build-version/version';

console.log('App Version:', version.version);
console.log('Build Date:', version.buildDate);
console.log('Commit:', version.shortSha);

// Display version in UI
document.getElementById('app').innerHTML = JSON.stringify(version, null, 2);
```

--------------------------------

### Webpack Integration with @shellicar/build-version

Source: https://context7.com/shellicar/build-version/llms.txt

Integrates the @shellicar/build-version plugin into a Webpack configuration. It shows how to import the plugin and pass configuration options, and how to access version information in the application's entry file.

```typescript
// webpack.config.js
import VersionPlugin from '@shellicar/build-version/webpack';

export default {
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: './dist',
  },
  plugins: [
    VersionPlugin({
      versionCalculator: 'git',
      debug: false,
      strict: true,
    }),
  ],
};

// src/index.js
import version from '@shellicar/build-version/version';

console.log(`Running version ${version.version} (${version.shortSha})`);
```

--------------------------------

### VersionInfo Interface Definition

Source: https://context7.com/shellicar/build-version/llms.txt

Defines the TypeScript interface for version information exposed by the plugin. It includes details like build date, Git branch, commit SHA (full and short), commit date, and semantic version.

```typescript
interface VersionInfo {
  buildDate: string;    // ISO timestamp when the build occurred
  branch: string;       // Git branch name (e.g., "main", "feature-auth")
  sha: string;          // Full Git commit SHA (40 characters)
  shortSha: string;     // Short Git commit SHA (7 characters)
  commitDate: string;   // ISO timestamp of the last commit
  version: string;      // Calculated semantic version
}

// Example output:
// {
//   "buildDate": "2024-01-15T10:30:00.000Z",
//   "branch": "main",
//   "sha": "abc123def456789012345678901234567890abcd",
//   "shortSha": "abc123d",
//   "commitDate": "2024-01-14T16:45:00.000Z",
//   "version": "1.2.3"
// }
```

--------------------------------

### Implement Custom Version Calculator in TypeScript

Source: https://context7.com/shellicar/build-version/llms.txt

Defines a custom version calculator function to override default versioning logic. This allows developers to return specific version strings and branch names based on custom business rules or environment variables.

```typescript
import VersionPlugin from '@shellicar/build-version/vite';
import type { Options } from '@shellicar/build-version/types';

type VersionCalculator = () => { version: string; branch: string };

const options: Options = {
  debug: true,
  strict: true,
  versionCalculator: () => ({
    branch: 'custom-branch',
    version: '1.0.0-custom',
  }),
};

export default defineConfig({
  plugins: [VersionPlugin(options)],
});
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.