Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/valencyhq/vanilla
Valency's Vanilla JS library
https://github.com/valencyhq/vanilla
assets-management cdn figma reactjs vanilla-js
Last synced: about 1 month ago
JSON representation
Valency's Vanilla JS library
- Host: GitHub
- URL: https://github.com/valencyhq/vanilla
- Owner: ValencyHQ
- License: other
- Created: 2021-04-27T14:53:54.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2021-05-22T15:40:36.000Z (over 3 years ago)
- Last Synced: 2024-11-12T16:47:08.687Z (about 1 month ago)
- Topics: assets-management, cdn, figma, reactjs, vanilla-js
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@valencyhq/valency
- Size: 1.99 MB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Valency
# 🤔 What is Valency?
Valency is a tool to manage and serve design assets.
- Design assets managed with Valency are served for use over a CDN.
## 📦 Install
```shell
npm install @valencyhq/valency --save
```
## Table of Contents
- [Quick Start](#quick-start)
- [Usage](#usage)
- [Client-side JavaScript](#🌐-client-side-javascript)
- [SVG Sprite & Icons](#🖋-svg-sprites-&-icons)
- [React](#⚛️-react)
- [Figma](#🎏-figma)
- [API Reference](#api-reference)
- [`valency.get()`](#valencygetfn)
- [`valency.get() shorthand properties`](#valencygetshorthandpropsfn)
- [`valency.replace()`](#valencyreplacefn)
- [`valency.loadSprite()`](#valencyloadpspritefn)
- [`valency.getConfig()`](#valencygetconfigfn)
- [`valency.setConfig()`](#valencysetconfigfn)
- [Contributing](#contributing)
- [License](#license)
## 🧪 Quick start
```html
![]()
var valent = new Valency({
uid: 'your user ID',
project: 'your project ID',
library: 'Your library ID',
})
valent.replace()
```
## 👨🎨 Usage
The following ways you can use assets served by Valency.
## 🌐 Client-side JavaScript
### 1. Install
> Note: If you intend to use Valency with a CDN, you can skip this installation step.
Install with npm.
```shell
npm install @valencyhq/valency --save
```
Or just copy valency.js or valency.min.js into your project directory. You don't need both valency.js and valency.min.js.
### 2. Include
Include valency.js or valency.min.js with a `` tag:
### 3. Use
To use an icon on your page, add a data-valency attribute with the icon name to an element:
```html
<img data-valency="man-dog" />
<object data-valency="man-dog"></object>
<div data-valency="man-dog">Your background image goes here</div>
```
### 4. Setup & Replace
Setup Valency with your credentials. Call the `valency.replace()` method:
```html
<script>
var valent = new Valency({
uid: 'Your user ID',
project: 'Your project ID',
library: 'Your library ID',
})
valent.replace()
```
All elements that have a `data-valency` attribute, their `src` or `data` atrribute will be replaced with the assset's URL corresponding to their `data-valency` attribute value.
See the API Reference for more information about [`valency.replace()`](#valencyreplaceattrs).
## 🖋 SVG Sprites & Icons
Valency serves icons packed into a single SVG sprite.
> If an icon in a icons library is not a vector `(PNG or JPG)`, it gets converted to `SVG`, then packed into the SVG sprite.
> For Valency to serve SVG Icon sprite for a library, the library's category must be `icon`
### 1. Usage
```html
```
Use `data-valency-lib` to set a library name if you don't want to use the default.
```html
```
## ⚛️ React
There is a wrapper library for React, have a look at [react-valency](https://github.com/ValencyHQ/react).
## 🎏 Figma
Valency is available as a Figma plugin. To use the plugin, log in to your Figma and install it. [Get it now!](https://www.figma.com/community/search?model_type=public_plugins&q=Valency)
## ⚙️ API Reference
## `valency.get(assetName, config?)`
Returns a URL to the provided `assetName`.
> If `config` argument is provided, it is used to generate the link instead of the default configuration set at instance of `Valency`.
## `valency.get() shorthand properties`
Valency provides convenient shorthand properties to `Valency.get()` which provides an intuitive way to get an asset's URL.
The shorthand format goes like this:
```js
valent.asset..url
valent.asset...url
valent.asset....url
valent.asset.....url
```
Let's show some sample `Valency.get()` usage with it's shorthand equivalent.
```js
const valent = new Valency({
uid: '9825624020',
project: 'PsSBtkjlQys',
library: 'LIB_i7J',
})
/** 🔖 EXAMPLE 1 **/
valent.get('blondeAvatar')
/**
* Shorthand 🤞
* valent.asset..url
*/
valent.asset.blondeAvatar.url
// returns https://cdn.valency.design/9825624020/PsSBtkjlQys/LIB_i7J/blondeAvatar
/** 🔖 EXAMPLE 2 **/
valent.get('03886')
/**
* Shorthand 🤞
* valent.asset..url
*/
valent.asset['03886'].url
// returns https://cdn.valency.design/9825624020/PsSBtkjlQys/LIB_i7J/03886
/** 🔖 EXAMPLE 3 **/
valent.get('latinoAvatar', {
library: 'LIB_3D_avatars',
})
/**
* Shorthand 🤞
* valent.asset...url
*/
valent.asset.Lib_3D_avatars.latinoAvatar.url
// returns https://cdn.valency.design/9825624020/PsSBtkjlQys/LIB_3D_avatars/latinoAvatar
/** 🔖 EXAMPLE 4 **/
valent.get('spaceship', {
library: 'LIB_i3m',
project: 'pNASA',
})
/**
* Shorthand 🤞
* valent.asset....url
*/
valent.asset.pNASA.LIB_i3m.spaceship.url
// returns https://cdn.valency.design/9825624020/pNASA/LIB_i3m/spaceship
/** 🔖 EXAMPLE 5 **/
valent.get('Mast Head.png', {
library: 'LIB_mcq',
project: 'pMaterial',
uid: '03786',
})
/**
* Shorthand 🤞
* valent.asset.....url
*/
valent.asset['03786'].pMaterial.LIB_mcq['Mast Head.png'].url
// returns https://cdn.valency.design/03786/pMaterial/LIB_mcq/Mast Head.png
```
## `valency.replace(config?, document?)`
All elements that have a `data-valency` attribute, their `src` atrribute will be replaced with the assset URL corresponding to their `data-valency` attribute value.
> If `config` is provided, it's merged with the base configuration. Note that whatever options contained in the `config` object takes precedence over the base configuration when they're merged together.
> If `document` is provided, it carries out replace on it instead of `window.document`.
## `valency.loadSprite(config?)`
Loads the SVG sprite of a library into the `DOM`.
> If `config` is provided, it's merged with the base configuration. Note that whatever options contained in the `config` object takes precedence over the base configuration when they're merged together.
## `valency.getConfig(otherConfig?)`
Returns configuration object.
> If `otherConfig` is provided, it's merged with the base configuration. Note that whatever options set in `otherConfig` takes precedence over the base configuration when they're merged together.
## `valency.setConfig(otherConfig)`
Use to globally update configuration.
## 👨🔧 Contributing
For more info on how to contribute please see the [contribution guidelines](./CONTRIBUTING.md).
Caught a mistake or want to contribute to the documentation? [Edit this page on Github](./README.md)
## 🧾 License
Valency is licensed under the [MIT License](https://github.com/ValencyHQ/vanilla/blob/master/LICENSE).