npm package: @imageboss/vue
Description: Vue 3 integration for ImageBoss - image resize, compress and CDN
Latest version: 1.0.0

# @imageboss/vue

Vue 3 integration for [ImageBoss](https://imageboss.me/) — image resize, compress and CDN..

## Features

- **IbImg** – responsive or fixed-size images with automatic `srcset`
- **IbPicture** – art-directed images with `<picture>` and multiple sources
- **IbSource** – `<source>` with ImageBoss `srcset` and optional `media`
- **buildUrl** / **buildSrcSet** / **buildUrlObject** – low-level URL helpers
- Vue 3.x compatible, TypeScript types included

## Install

```bash
npm install @imageboss/vue
# or
yarn add @imageboss/vue
pnpm add @imageboss/vue
```

## Setup

Configure the plugin with your ImageBoss **source** (from your [dashboard](https://imageboss.me/dashboard/sources)):

```ts
// main.ts
import { createApp } from 'vue';
import ImageBossVue from '@imageboss/vue';
import App from './App.vue';

const app = createApp(App);
app.use(ImageBossVue, {
  source: 'mywebsite-images',
  defaultParams: { options: 'format:auto' }, // optional
});
app.mount('#app');
```

## Usage

### IbImg – responsive image

```vue
<template>
  <ib-img
    src="/path/to/image.jpg"
    sizes="100vw"
    width="16"
    height="9"
    alt="Responsive image"
  />
</template>
```

- **src** – path to the image (relative to your ImageBoss source).
- **sizes** – e.g. `"100vw"` or `"(min-width: 800px) 50vw"` (see [sizes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes)).
- **width** / **height** – aspect-ratio hint (any proportional values).

### IbImg – fixed size (cover)

```vue
<ib-img
  src="/path/to/image.jpg"
  fixed
  :width="320"
  :height="320"
  alt="Square thumbnail"
/>
```

### IbImg with ImageBoss params

```vue
<ib-img
  src="/path/to/image.jpg"
  :img-params="{
    operation: 'cover:center',
    width: 400,
    height: 300,
    options: 'blur:2'
  }"
  sizes="(min-width: 600px) 400px, 100vw"
/>
```

**Operations:** `cdn`, `width`, `height`, `cover`, or `cover:mode` (e.g. `cover:center`, `cover:smart`, `cover:face`).
**options:** ImageBoss options string, e.g. `format:auto`, `blur:2`, `grayscale:true`.

### IbPicture + IbSource

```vue
<ib-picture>
  <ib-source
    src="/path/to/image.jpg"
    :img-params="{ operation: 'width', width: 800 }"
    media="(min-width: 800px)"
  />
  <ib-source
    src="/path/to/image.jpg"
    :img-params="{ operation: 'width', width: 400 }"
    media="(min-width: 400px)"
  />
  <ib-img
    src="/path/to/image.jpg"
    :img-params="{ operation: 'width', width: 200 }"
    alt="Fallback"
  />
</ib-picture>
```

### Low-level API

```ts
import { buildUrl, buildUrlObject, buildSrcSet } from '@imageboss/vue';

// Single URL
const url = buildUrl('/images/photo.jpg', {
  operation: 'cover',
  width: 500,
  height: 300,
  options: 'format:auto',
});

// src + srcset for manual <img> or other components
const { src, srcset } = buildUrlObject('/images/photo.jpg', {
  operation: 'width',
  width: 600,
}, { widths: [400, 600, 800] });

const srcsetOnly = buildSrcSet('/images/photo.jpg', { operation: 'width' }, { minWidth: 100, maxWidth: 1200 });
```

## ImageBoss URL format

URLs follow ImageBoss conventions:

- **cdn:** `https://img.imageboss.me/{source}/cdn/path`
- **width:** `https://img.imageboss.me/{source}/width/{w}/path`
- **height:** `https://img.imageboss.me/{source}/height/{h}/path`
- **cover:** `https://img.imageboss.me/{source}/cover/{w}x{h}/path` (or `cover:mode`)

See [ImageBoss docs](https://imageboss.me/docs) for operations and options.

## Playground

From the repo:

```bash
npm run playground
```

Opens a small Vue app at `http://localhost:5174` that demos IbImg, IbPicture, IbSource, and the URL helpers. Replace the `source` in `playground/src/main.ts` with your own to load real images.

## Versioning and releases

This repo uses [Changesets](https://github.com/changesets/changesets):

- **Add a changeset:** `npm run changeset`
- **Apply version bumps:** `npm run version`
- **Build and publish:** `npm run release`

## License

MIT