Marfeel Docs

# Using NPM

Marfeel Extensions are all built using NPM. Whether you are developing, debugging or simply using one, you might need more than the basic npm install.

This guide shows all the npm commands you need when working with providers. It works for paywalls, widgets, ad servers and analytics providers in exactly the same way.

# Debug a provider in local

By default, when you compile a tenant in you local environment, you are using the published provider, with the version specified in your package.json.

You can always go and see the provider's code in your node_modules folder.

However, this code is minified, and impossible to work with. If you want to debug step-by-step a provider's code, whether you have made changes to it or you are simply hunting down a bug, you need readable code.

This is where npm link comes in: it lets you use your local version of the provider instead of the published one.

  1. Cloning the Provider you work with. Clone it directly with git, there is no Marfeel-specific command.

For example:

git clone git@github.com:Marfeel/analytics-providers-comscore.git

TIP

This example uses an Analytics Provider, but it works with all Marfeel Providers.

  1. Enter the provider folder and run npm link.

At the end of the output, it shows it created a symlink between your node modules cache and your provider:

cd analytics-providers-comscore
$ npm link
...
/Users/user/.nvm/versions/node/v12.16.3/lib/node_modules/@marfeel/analytics-providers-comscore -> /Users/user/Marfeel/analytics/analytics-providers-comscore
  1. Still in the provider folder, build a development version:
npm run build:dev

WARNING

If you build without the dev suffix, you're back to square one: the script you will see in the tenant will be from your local environment, but unreadable.

  1. Go to the Media Group repository you want to work with, and run:
npm install
$ npm link @marfeel/analytics-providers-comscore
...
/Users/user/Marfeel/ProTenants/Mediagroup/node_modules/@marfeel/analytics-providers-comscore -> /Users/user/.nvm/versions/node/v12.16.0/lib/node_modules/@marfeel/analytics-providers-comscore -> /Users/user/Marfeel/analytics/analytics-providers-comscore

WARNING

Always run npm install before npm link in the Media Group repository.

Otherwise, the linking is overwritten.

  1. And finally, build the tenant's scripts:
jinks --coredll # Only for Paywall providers
npm run build

TIP

Remember to add the -- -v react option to npm run build if you're in one of those cases:

  • You're debugging a widget provider
  • The tenant uses react.
  1. And start debugging your local version of the tenant's website, in the dev tools!

In the Sources tab, you will find all the providers' files:

Dev tools Sources tab

# Testing before deploying

Validating that a provider works in development mode is nice. But packaged code can behave differently! Even with npm link and a production build, you don't have the complete picture.

There are two main reasons why you'd want to test your provider as a package:

  • NPM packages are tar archives: the code is packaged differently than with symlinks.
  • When your provider script imports code from a dependency: if that's a dependency the tenant also has, like react for example, different versions will lead to conflicts!

npm pack is the command you need to avoid those problems. It lets you test your new provider code in exactly the same conditions as if it was published, while staying in your local environment.

To test your provider in real conditions, follow the steps:

  1. From the provider repository, package the code, and copy the result somewhere you won't lose it, like your home:
npm pack
cp marfeel-analytics-providers-comscore-1.0.20.tgz ~
  1. In the Media Group repository, install all the dependencies if you haven't already, and then install your new, local package:
npm i
npm i ~/marfeel-analytics-providers-comscore-1.0.20.tgz

WARNING

Always run npm install before installing your provider package, to avoid it getting overwritten.

  1. Build the tenant's scripts:
jinks --coredll # Only for Paywall providers
npm run build

TIP

Remember to add the -- -v react option to npm run build if you're in one of those cases:

  • You're debugging a widget provider
  • The tenant uses react.

  1. And open the tenant in your local! The provider will look just like the "real" one, but using the modified version from your local environment.

  2. Clean up before committing.

Notice that the tenant's package.json was updated with your local package:

"@marfeel/analytics-providers-comscore": "file:../../../marfeel-analyt
ics-providers-comscore-1.0.20.tgz"

Reinstall the correct, published version before committing!

The same applies for the package-lock.json file.

← Write an OnExtraction Middleware →