Skip to content

Commit

Permalink
Merge pull request #47 from SpiriitLabs/dev
Browse files Browse the repository at this point in the history
Version 2.3.0
  • Loading branch information
Applelo authored Oct 9, 2024
2 parents 4cc9000 + 4afcff8 commit 44d8ff4
Show file tree
Hide file tree
Showing 65 changed files with 9,374 additions and 7,009 deletions.
45 changes: 14 additions & 31 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,16 +20,14 @@ jobs:
name: 'Build: node-20, ubuntu-latest'

steps:
- uses: actions/checkout@v3
- uses: actions/checkout@v4
with:
fetch-depth: 0

- uses: pnpm/action-setup@v2
with:
version: 8
- uses: pnpm/action-setup@v4

- name: Set node version to 20
uses: actions/setup-node@v3
uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
Expand All @@ -47,7 +45,7 @@ jobs:
strategy:
matrix:
os: [ubuntu-latest]
node_version: [14, 16, 18, 20]
node_version: [18, 20]
include:
# Active LTS + other OS
- os: macos-latest
Expand All @@ -57,20 +55,15 @@ jobs:
fail-fast: false

steps:
- uses: actions/checkout@v3

- name: Install pnpm (node 14, pnpm 7)
if: matrix.node_version == 14
uses: pnpm/action-setup@v2.2.4
- uses: actions/checkout@v4
with:
version: 7
fetch-depth: 0

- name: Install pnpm
if: matrix.node_version != 14
uses: pnpm/action-setup@v2.2.4
uses: pnpm/action-setup@v4

- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v3
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: pnpm
Expand All @@ -88,9 +81,6 @@ jobs:
- name: Build
run: pnpm build

- name: Install Playwright
run: npx playwright install

- name: Test
run: pnpm test

Expand All @@ -106,26 +96,21 @@ jobs:
name: 'Coverage: node-20, ubuntu-latest'

steps:
- uses: actions/checkout@v3
- uses: actions/checkout@v4
with:
fetch-depth: 0

- uses: pnpm/action-setup@v2
with:
version: 8
- uses: pnpm/action-setup@v4

- name: Set node version to 20
uses: actions/setup-node@v3
uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm

- name: Install
run: pnpm install

- name: Install Playwright
run: npx playwright install

- name: Test
run: pnpm coverage

Expand All @@ -139,16 +124,14 @@ jobs:
name: 'Lint: node-20, ubuntu-latest'

steps:
- uses: actions/checkout@v3
- uses: actions/checkout@v4
with:
fetch-depth: 0

- uses: pnpm/action-setup@v2
with:
version: 8
- uses: pnpm/action-setup@v4

- name: Set node version to 20
uses: actions/setup-node@v3
uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
Expand Down
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,5 @@ coverage
.svelte-kit
demo/server/public
.nitro
test/fixtures/basic/styles/*
!test/fixtures/basic/styles/.gitkeep
112 changes: 103 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ This ViteJS plugin generates a single SVG [spritemap](https://css-tricks.com/svg

The plugin outputs can be fully configurable through [options](#🛠-options).

> [!NOTE]
> This plugin is inspired by [svg-spritemap-webpack-plugin](https://github.com/cascornelissen/svg-spritemap-webpack-plugin) for Webpack.
## 🚀 Features
Expand Down Expand Up @@ -96,18 +97,79 @@ You can see the usage in the demo folder :
- [Less](/demo/basic/src/less/)
- [Stylus](/demo/basic/src/stylus/)

### Use Vue components
## Advanced

### Customize styles outputs

By default, the plugin will generate CSS or a mixin (for SCSS, Less and Stylus) with variables which contains all sprites data.

You can alter the output by using the `styles.callback`. You can access the default content generated by the plugin but you can also write your own output by using the createSpritemap function.

In the example below, this will generate only background data uri.

```ts
// vite.config.js / vite.config.ts
import VitePluginSVGSpritemap from '@spiriit/vite-plugin-svg-spritemap'

export default {
plugins: [
VitePluginSVGSpritemap('./src/icons/*.svg', {
styles: {
filename: 'src/scss/spritemap.css',
callback: ({ content, options, createSpritemap }) => {
let insert = ''
insert += createSpritemap((name, svg) => {
const selector = `.${options.prefix}${name}`
let sprite = ''
sprite = `${selector} {`
sprite += `\n\tbackground: url("${svg.svgDataUri}") center no-repeat;`
sprite += '\n}'
return sprite
})
return insert
}
}
})
]
}
```

You can use the `include` property to controle exactly what to include inside your style. If you want only variables with `['variables']` for SCSS/Less/Stylus or `['bg']` in CSS, only background css class generation for example.

You can also control the names of the `mixin`, the variables `sprites` and `prefix`.

```ts
// vite.config.js / vite.config.ts
import VitePluginSVGSpritemap from '@spiriit/vite-plugin-svg-spritemap'

export default {
plugins: [
VitePluginSVGSpritemap('./src/icons/*.svg', {
styles: {
filename: 'src/scss/spritemap.scss',
names: {
mixin: 'icon-sprite',
prefix: 'icon-prefix',
sprites: 'icons'
}
}
})
]
}
```

### Vue components

`vite-plugin-svg-spritemap` allows you to load icons and create `<use>` as `<svg>` and `<view>` as `<img>` tags like Vue components.

To do that, import the icons loaded by `vite-svg-spritemap` and add the `?use` or `?view` query. The plugin will transform the component.

```vue
<script setup lang="ts">
import SpiriitView from './icons/spiriit.svg?view'
import SpiriitUse from './icons/spiriit.svg?use'
import ViteView from './icons/vite.svg?view'
import SpiriitView from './icons/spiriit.svg?view'
import ViteUse from './icons/vite.svg?use'
import ViteView from './icons/vite.svg?view'
</script>
<template>
Expand Down Expand Up @@ -147,7 +209,7 @@ For typescript, you need to load the type definitions inside `vite-env.d.ts` to
/// <reference types="@spiriit/vite-plugin-svg-spritemap/client" />
```

### Usage with Nuxt 3
### Nuxt 3

> [!NOTE]
> This plugin only works with Nuxt 3 and Vite as a bundler.
Expand Down Expand Up @@ -177,7 +239,7 @@ For usage with TypeScript, you will need to add in a `.d.ts` file the reference
/// <reference types="@spiriit/vite-plugin-svg-spritemap/dist/client" />
```

### Use for backend integration
### Backend integration

ViteJS allows to be use to [serve assets](https://vitejs.dev/guide/backend-integration.html). So, you can connect ViteJS with Wordpress, Drupal or any kind of backend.

Expand Down Expand Up @@ -207,6 +269,26 @@ To prevent [CORS issue with SVG](https://oreillymedia.github.io/Using_SVG/extras

You can see an example of integration in the [corresponding demo folder](/demo/server/routes/index.pug).

### Multiple Instance

If you want to have multiple SVG sprites files, you can configure multiple instances of the plugin. To do so, you will need the options `route`. Instead of the traditionnal `/__spritemap`, you can set for example `/__flags`.

```ts
// vite.config.js / vite.config.ts
import VitePluginSVGSpritemap from '@spiriit/vite-plugin-svg-spritemap'

export default {
plugins: [
VitePluginSVGSpritemap('./src/icons/*.svg'), // will be route: '__spritemap' by default
VitePluginSVGSpritemap('./src/flags/*.svg', {
route: '__flags'
})
]
}
```

If you are using Sass, Less or Stylus: you can optimize the style file export by only generate one mixin on one instance with `styles.include` set to `['variables']` or/and use the `styles.names` object.

## 🛠 Options

The first argument is a glob path (using [fast-glob](https://github.com/mrmlnc/fast-glob)) and the second is an object with the following options :
Expand All @@ -219,6 +301,7 @@ The first argument is a glob path (using [fast-glob](https://github.com/mrmlnc/f
| svgo | `boolean` or `object` | `true` | Take an SVGO Options object.<br> If `true`, it will use the [default SVGO preset](https://github.com/svg/svgo#default-preset), if `false`, it will disable SVGO optimization |
| injectSVGOnDev | `boolean` | `false` | Inject the SVG Spritemap inside the body on dev |
| idify | `(name:string, svg:object) => string` | `name => options.prefix + name` | Function allowing to customize the id of each symbol of the spritemap svg. |
| route | `string` | `__spritemap` | Change the route name allowing you to have multiple instance of the plugin |

### output

Expand All @@ -234,7 +317,10 @@ The first argument is a glob path (using [fast-glob](https://github.com/mrmlnc/f
| Options | Type | Description |
| -------- | ----------------------------------------- | -------------------------------------------------------------- |
| filename | string | The destination of the stylesheet file like your source folder |
| lang | `less`/`scss`/`styl`/`css` or `undefined` |
| lang | `less`/`scss`/`styl`/`css` or `undefined` |Enforce the styles language generated by the plugin |
| include | boolean or `['mixin', 'variables']` or `['bg', 'mask', 'bg-frag']` or `undefined` | By default, it will include `['mixin', 'variables']` for SCSS/Less/Stylus and `['bg', 'mask', 'bg-frag']` for CSS. This allowing you to choose what to include |
| names | `{prefix: 'sprites-prefix', sprites: 'sprites', mixin: 'sprite'}` | Allow to customize the variables/mixin names of the generated Sass/Less/Stylus |
| callback | `undefined` | Allow you to customize the output of the generated styles file (see [Customize Styles Outputs](#customize-styles-outputs)) |

**Example with full options :**

Expand All @@ -246,6 +332,7 @@ export default {
plugins: [
VitePluginSVGSpritemap('./src/icons/*.svg', {
prefix: 'icon-',
route: '__spritemap',
output: {
filename: '[name].[hash][extname]',
name: 'spritemap.svg',
Expand All @@ -263,7 +350,16 @@ export default {
idefy: (name, svg) => `icon-${name}-cheese`,
styles: {
lang: 'scss',
filename: 'src/scss/spritemap.scss'
filename: 'src/scss/spritemap.scss',
include: ['mixin', 'variables'],
names: {
prefix: 'sprites-prefix',
sprites: 'sprites',
mixin: 'sprite',
},
callback: ({ content, options, createSpritemap }) => {
return content
}
}
})
]
Expand All @@ -272,8 +368,6 @@ export default {

## 🏃 What's next

- [Support multiple instance of the plugin](https://github.com/SpiriitLabs/vite-plugin-svg-spritemap/issues/39)
- [CSS generation callback](https://github.com/SpiriitLabs/vite-plugin-svg-spritemap/issues/16)
- Add variable supports inspired by [svg-spritemap-webpack-plugin](https://github.com/cascornelissen/svg-spritemap-webpack-plugin/blob/master/docs/variables.md)

## 👨‍💼 Licence
Expand Down
1 change: 1 addition & 0 deletions demo/_fixtures/flags/CH.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions demo/_fixtures/flags/FR.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions demo/_fixtures/flags/JP.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions demo/_fixtures/icons/no_viewbox.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
52 changes: 52 additions & 0 deletions demo/_fixtures/scss/spritemap-flags.scss
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
/* Generated by vite-plugin-svg-spritemap */

$flags-prefix: 'flag-';
$flags: (
'CH': (
uri: "data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 85.333 513 342'%3e%3cpath fill='red' d='M0 85.337h513v342H0z'/%3e%3cpath fill='white' d='M356.174 222.609h-66.783v-66.783h-66.782v66.783h-66.783v66.782h66.783v66.783h66.782v-66.783h66.783z'/%3e%3c/svg%3e",
width: 513px,
height: 342px
),
'FR': (
uri: "data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 513 342'%3e%3cpath fill='white' d='M0 0h513v342H0z'/%3e%3cpath fill='%230052B4' d='M0 0h171v342H0z'/%3e%3cpath fill='%23D80027' d='M342 0h171v342H342z'/%3e%3c/svg%3e",
width: 513px,
height: 342px
),
'JP': (
uri: "data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 513 342'%3e%3cpath fill='white' d='M0 0h512v342H0z'/%3e%3ccircle cx='256.5' cy='171' r='96' fill='%23D80027'/%3e%3c/svg%3e",
width: 513px,
height: 342px
)
);

@mixin sprites-flags(
$name,
$include-size: false,
$type: 'uri',
$mode: 'background',
$route: '__flags'
) {
$sprite: map-get($flags, $name);
$url: false;

@if $type == 'fragment' {
$url: '/#{$route}##{$flags-prefix}#{$name}-view';
} @else if $type == 'uri' {
$url: map-get($sprite, uri);
} @else {
@error 'sprite(): $type must be either "fragment" or "uri"';
}

@if $url {
#{$mode}: url($url) center no-repeat;

@if $include-size {
@if $include-size == true {
#{$mode}-size: map-get($sprite, width) map-get($sprite, height);
} @else if $include-size == 'box' {
width: map-get($sprite, width);
height: map-get($sprite, height);
}
}
}
}
Loading

0 comments on commit 44d8ff4

Please sign in to comment.