npm package: @meowkj/fluent-emoji-assets
Description: Reusable Node-friendly helpers for Microsoft Fluent Emoji CDN URLs
Latest version: 0.1.0

# @meowkj/fluent-emoji-assets

Reusable Node-friendly helpers for generating Microsoft Fluent Emoji asset URLs with CDN support.

This package is meant for teams that want one consistent way to use Windows 11 style Fluent Emoji assets across many Node, Vue, React, or static-web projects.

[![npm version](https://img.shields.io/npm/v/%40meowkj%2Ffluent-emoji-assets?color=4cc2ff)](https://www.npmjs.com/package/@meowkj/fluent-emoji-assets)
[![license](https://img.shields.io/badge/license-MIT-8bd3dd)](./LICENSE)

## Features

- Semantic alias catalog such as `cat`, `clipboard`, `warning`
- Stable URL generation for Microsoft Fluent Emoji assets
- CDN support for `jsdelivr` and `rawGithub`
- Zero runtime dependencies
- ESM-first package with TypeScript declarations
- Works nicely with `pnpm`, `npm`, and frontend wrappers

## Why

Microsoft Fluent Emoji 3D assets are image files, not a normal web font.

For multi-project reuse, the cleanest pattern is:

- keep a semantic emoji catalog in code
- generate upstream asset URLs from one place
- let each project decide how to render them

That means this package works as a shared source of truth, while your apps stay free to use:

- `<img>`
- Vue / React wrapper components
- CSS backgrounds
- build-time asset transforms

## Install

### Local development install

```bash
pnpm add /Users/kj/Desktop/fluent-emoji-assets
```

### From npm after publishing

```bash
pnpm add @meowkj/fluent-emoji-assets
```

## Quick Start

```js
import {
  createFluentEmojiClient,
  getFluentEmojiMeta,
  getFluentEmojiUrl
} from '@meowkj/fluent-emoji-assets'

const catUrl = getFluentEmojiUrl('cat')
const warningMeta = getFluentEmojiMeta('warning')

const emoji = createFluentEmojiClient({
  provider: 'jsdelivr',
  repo: {
    ref: 'main'
  }
})

console.log(catUrl)
console.log(warningMeta)
console.log(emoji.url('clipboard'))
```

## API

### `getFluentEmojiUrl(name, options?)`

Returns a CDN URL from a semantic alias.

```js
getFluentEmojiUrl('warning')
```

### `getFluentEmojiMeta(name)`

Returns:

- `assetName`
- `fallback`

### `hasFluentEmoji(name)`

Checks whether a semantic alias exists.

### `listFluentEmojiNames()`

Returns all supported aliases.

### `buildFluentEmojiAssetPath(assetName, options?)`

Builds the upstream repo-relative asset path from an official asset name.

### `buildFluentEmojiUrl(assetName, options?)`

Builds a direct asset URL from an official asset name.

### `createFluentEmojiClient(defaults?)`

Creates a reusable client with shared defaults.

```js
const emoji = createFluentEmojiClient({
  provider: 'jsdelivr',
  repo: { ref: 'main' }
})

emoji.url('cat')
emoji.rawUrl('Clipboard')
```

## Supported Providers

- `jsdelivr`
- `rawGithub`

Default provider:

- `jsdelivr`

## Notes

- Default style is `3D`
- Default upstream target is `microsoft/fluentui-emoji@main`
- For production apps, pinning `repo.ref` to a tag or commit SHA is safer than following `main`
- This package does not bundle upstream emoji binaries

## Example Integration Pattern

Typical reuse looks like this:

1. Use this package in a shared design/util package
2. Build a small framework wrapper for your frontend stack
3. Keep aliases like `warning`, `clipboard`, `cat`, and `gear` in app code

That gives you one place to manage asset routing and fallback behavior.

## Development

```bash
pnpm test
```

The test suite uses the built-in Node test runner and does not require extra dependencies.

## Upstream References

- Microsoft Fluent Emoji repository: https://github.com/microsoft/fluentui-emoji
- jsDelivr documentation: https://www.jsdelivr.com/documentation

This package is based on upstream repository layout plus CDN URL conventions. Please review upstream asset availability and licensing before publishing your own wrappers.

## License

MIT