Velo: Working with Velo Packages

Velo packages are code libraries written using Velo code that allow you to add specific functionality to your site, without spending hours writing complex code. You can add Velo packages to your site. If no existing Velo package meets your needs, you can create a custom app with Wix Blocks.

These are some of the advantages of using Velo packages:

• The use cases for Velo packages are specific to Wix websites.
• Velo packages work seamlessly with Wix elements and apps. 
• You can view all the code used to implement a Velo package.
• Each Velo package contains a detailed README file explaining the package's functionality and the steps required for implementation.

Package Content

Velo packages can include read-only backend code files, public code files, and npm packages. An editable config.json file may also be included for defining specific settings for your package.

A package's functionality is available for use through its exported functions, which can be imported and used in your code.

Setting Up a Package

Velo packages can work with Wix apps or include integrations with 3rd-party services, and may require initial setup and configuration before use. To set up your site to use a package, follow the steps in the Setup section of the package's README file. Package prerequisites may include: 

• Creating an account with a 3rd-party service.
• Storing API keys and other secrets from a 3rd-party service in the Secrets Manager. 
• Adding a Wix App to your site. For example, you might need to add a Wix Store or a Member's Area to your site.
• Editing the package's config.json file to define specific settings that affect how the package works on your site.

Backend Events

A package may also include an events.js file for running backend events related to the package. You do not need to perform any action to run the backend events. Just like backend events are defined in your site's events.js file, events in your package's events.js are triggered automatically once you have published your site and the specific conditions associated with the event are met.

Installing a Package

To install a package:

1. Go to the Packages & Apps section of the Code sidebar (Wix Editor) or the Code sidebar (Wix Studio). Under Velo Packages click Install Velo Package.

2. The Package Manager opens.

   

3. In the Built by Wix tab, search for the package you want to add to your site. Note that you can view the README for each package on the right side of the Package Manager.

4. Click Install. The Install button changes to a View button, and you can see an option to turn on automatic updates for future minor versions. When this option is turned on, you won't need to do anything if there are any minor updates to the package. When this option is turned off, you'll have to manually update the package if there are any minor updates to the package.

   

   Clicking View directs you to the Packages & Apps section of the Code sidebar (Wix Editor) or Code sidebar (Wix Studio) where you can see the installed Velo package. If there is a major update available for a package installed on your site, or if there is a minor update available and the automatic updates option toggle is turned off, you'll see a blue dot next to the package. 

Using an Installed Package

Once you install a package, read the package's README file. The README includes all the information you need to work with the package: initial setup prerequisites, which exported functions are available for use, and how to use the package. 

To use the package functions, you'll need to import them in your code. 

Use the @velo namespace to import Velo packages. Note that import statements within the @velo namespace differ depending on the location and type of package file the function is exported from. 

To import backend functions, use the following syntax:

For example, assuming the twitter-integration package has been installed, you can use its tweet() function as follows:

To import public functions, use the following syntax:

For example, assuming the wix-data-helpers package has been installed, you can use its getRandomItem() function as follows:

To learn more about which import statements to use for each Velo package, see the package's README file.

Package Examples

To help you understand how to use specific Velo packages on your site, we added some examples to the Velo Examples page that integrate Velo packages. You can open an example site and see the code we added to work with the package. You'll see a Velo Package tag on examples that integrate a Velo Package.

Updating a Package's Version

If there is a minor update to a package installed on your site:

• If the automatic updates option toggle is turned on, the package will update automatically. 
• If the automatic updates option toggle is turned off, you'll see a blue dot next to the package in the Code sidebar. 

If there is a major update to a package installed on your site, you'll see a blue dot next to the package in the Code sidebar. 

To update the package on your site:

1. Hover over the dot and click See Release Notes in the tooltip.

   

   The Package Manager opens and you can see the available update.

   

2. In the README on the right side of the Package Manager, scroll down to the Release Notes section to view the relevant changes for this update.

3. If you want to update the package, click Update to X.X.X.

You can view all versions of a package by clicking the ellipsis icon > See all versions. 

Uninstalling a Package

To uninstall a package:

1. In the Velo Packages section of the Code sidebar (Wix Editor) or the Code sidebar (Wix Studio), hover over the package you want to uninstall. Click the ellipsis icon, and select Uninstall.
2. The package is removed from the Velo Packages section of the Code sidebar (Wix Editor) or the Code Sidebar (Wix Studio).

Requesting a Package

To request that a package be added to the list of Velo packages built by Wix, click Make a request for a new Velo package at the bottom of the Package Manager.

You can also request a new Velo package from Wix using the Velo Wishlist.