woocommerce/packages/js

WooCommerce Packages

Currently we have a set of public-facing packages that can be dowloaded from npm and used in external applications. Here is a non-exhaustive list.

• @woocommerce/components: A library of components that can be used to create pages in the WooCommerce dashboard and reports pages.
• @woocommerce/csv-export: A set of functions to convert data into CSV values, and enable a browser download of the CSV data.
• @woocommerce/currency: A class to display and work with currency values.
• @woocommerce/date: A collection of utilities to display and work with date values.
• @woocommerce/navigation: A collection of navigation-related functions for handling query parameter objects, serializing query parameters, updating query parameters, and triggering path changes.
• @woocommerce/tracks: User event tracking utility functions for Automattic based projects.

Working with existing packages

• You can make changes to packages files as normal, and running pnpm start will compile and watch both app files and packages.
• ⚠️ Add any dependencies to a package using pnpm add from the package root.
• ⚠️ Make sure you're not importing from any other files outside of the package (you can import from other packages, just use the import from @woocommerce/package syntax).
• Don't change the version in package.json.
• Label your PR with the Packages label.
• See the Package Release Tool for instructions on how to release packages.

---

Creating a new package

Most of this is pulled from the Gutenberg workflow.

To create a new package, add a new folder to /packages, containing…

1. package.json based on the template:

   {
    "name": "@woocommerce/package-name",
    "version": "1.0.0-beta.0",
    "description": "Package description.",
    "author": "Automattic",
    "license": "GPL-2.0-or-later",
    "keywords": [ "wordpress", "woocommerce" ],
    "homepage": "https://github.com/woocommerce/woocommerce/tree/trunk/packages/js/[_YOUR_PACKAGE_]/README.md",
    "repository": {
     "type": "git",
     "url": "https://github.com/woocommerce/woocommerce.git"
    },
    "bugs": {
     "url": "https://github.com/woocommerce/woocommerce/issues"
    },
    "main": "build/index.js",
    "module": "build-module/index.js",
    "react-native": "src/index",
    "publishConfig": {
     "access": "public"
    }
   }
   

2. .npmrc file which disables creating package-lock.json file for the package:

   package-lock=false
   

3. README.md file containing at least:

   • Package name
   • Package description
   • Installation details
   • Usage example

4. A src directory for the source of your module. Note that you'll want an index.js file that exports the package contents, see other packages for examples.

5. A blank Changelog file, changelog.md.

   # Changelog
   
   This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   

6. Add the new package name to packages/js/dependency-extraction-webpack-plugin/assets/packages.js so that users of that plugin will also be able to use the new package without enqueuing it.