Velo: Working with npm Packages

The most popular registry of reusable JavaScript code is npm. In npm, each reusable library of code is known as a package. Velo allows you to install public npm packages in your site directly from the npm registry. Once installed, you can import the package and use it in your code.

Installing a Package

To install a package:

  1. Go to Packages & Apps:

    • Wix Studio: Select Packages & Apps in the Code sidebar.
    • Wix Editor: Select Packages & Apps in the Velo sidebar.
  2. Hover over npm in Packages & Apps, click the plus icon , and select Install npm package.

    The Package Manager opens.

  3. In the npm section, search for the package you want to add to your site. Note that the 10 most popular npm packages used in Wix sites are displayed, and instructions on how to use these packages in your Wix site are available on the right side of the Package Manager above the package's README.

  4. On the top right side of the package manager, review the Indications of a safe package instructions.

  5. Click Install next to the package of your choice. The installed package is added to the npm Packages section of the Code sidebar (Wix Studio) or the Velo sidebar (Wix Editor).

Important By installing an npm package, you agree to that npm module's license agreement.

Using an Installed Package

To use an installed package, import the package in your code. Each package will have a unique import statement. See the package's external documentation to learn about what import statement to use.

For example, assuming the lodash package has been installed, you can use its functionality as follows:

Copy
1
// Import the package in your code:
2
import _ from 'lodash';
3
4
// Use the following code to union two arrays:
5
let unionArray = _.union([1, 2, 3], [3, 4, 5]);
6
// unionArray = [1,2,3,4,5]

You can see the package's file structure in the Packages & Apps section of the code sidebar (Wix Studio) or the Velo sidebar (Wix Editor). You can see the package's README file in the Package Manager. For the top 10 npm packages, you can see instructions on how to use the package on your site at the top of the package's README file.

You can also open the package's README file and see other information about the package in a new browser tab at npmjs.com. Hover over the package, click the Show More  icon, and select See Documentation. Alternative you can click View on your installed package. This will open the README file within your editor.

Package Examples

To help you understand how to use specific npm packages on your site, we added some examples that integrate npm packages to the Velo Examples page. You can open an example and see the code we added to work with the package. To find npm examples, enter 'npm' in the Examples page search bar.

Updating a Package's Version

To update a package to its latest version:

  1. Open the Package Manager and select Installed Packages.
  2. Hover over the package and click the button.
    • If there is no option to update the package, the installed version is the latest version of that package. It is tagged as "Installed."
    • If the package is not the latest version: Click Update to X.X.X to update the package to the latest version.

Important After applying a package update, make sure that the code on your site is compatible with the updated version of the package.

Uninstalling a Package

To uninstall a package:

  1. Hover over the package you want to uninstall from the Packages (npm) section of the Velo  sidebar, click the Show More icon, and select Uninstall.
  2. The uninstalled package is removed from the Packages (npm) section of Code sidebar (Wix Studio) or the Velo sidebar (Wix Editor).

Warning When you uninstall a package, you may break code that relies on that package.

Package Support

It is your responsibility to understand the package's functionality, in what situations it can be used, and in what situations it should not be used. Some types of packages are not supported. These include private packages, packages that need to run on specific hardware, and packages that may expose a security risk.

Here are a few things to consider when using a public package in your code:

  • Some packages are only intended to be used in client-side code and others are only intended to be used in server-side code. Be sure to use packages in their intended locations.
  • Some packages contain functionality that interacts with the DOM. In Velo, you use $w APIs to interact with page elements instead of interacting directly with the DOM, so some functionality in these packages will not work.
  • Some packages work with React. You can only use these packages in conjunction with custom elements.
  • Errors that occur when using a package's functionality may be reflected in the browser console. These errors are generated by the implementation of the package, not from Velo. See the package's documentation to get a better understand what is causing the error.

Package Limitations

  • ESM modules are incompatible with Velo.
  • A package will not execute during runtime unless it aligns with Velo's current Node.js version.
  • Packages containing native modules are not compatible.
  • Velo has runtime limitations; terminal commands are not supported.
  • For a package to be Velo compliant, all its dependent packages must also be compliant. Otherwise, the package may not run.

Performance

  • Importing npm packages in client-side code increases the page's payload and may adversely affect your site's performance.
Was this helpful?
Yes
No