Get ready to publish Alloy as an NPM repo #637

jonsnyder · 2020-11-13T23:40:34Z

Description

This PR gets the repo ready to be published as an NPM library. Other PRs will automate the build process. The NPM library publishes an ES6 module which exposes the baseCode, core initialization, and the createEventMergeId functions. The built baseCode and standalone javascript files are not published in the NPM library. If you want to use the built versions you should use the version on the CDN.

See #632

There are three entry points now:

src/baseCode.js - used to generate the base code snippet
src/standAlone.js - used to generate the standalone code
src/index.js - used to generate the ES6 modules

I was also able to remove the REACTOR pre-processor statements, as the launch extension can use the ES6 module and the createEventMergeId directly.

Related Issue

https://jira.corp.adobe.com/browse/CORE-52500

Motivation and Context

We don't want to have to copy built files as part of the Launch Extension release process. The launch extension can use the NPM library to integrate.
Publishing an NPM library allows customers to integrate with their javascript build system.
If we were to export more modules we could allow customers to do custom builds. (i.e. exclude the personalization module).

Screenshots (if appropriate):

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Improvement (non-breaking change which does not add functionality)
Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

I have signed the Adobe Open Source CLA or I'm an Adobe employee.
I have made any necessary test changes and all tests pass.
I have run the Sandbox successfully.

jfkhoury · 2020-11-15T14:53:10Z

package.json

@@ -1,8 +1,13 @@
 {
  "name": "@adobe/alloy",
  "version": "2.3.0",
-  "description": "Client-Side SDK for Unified Data Collection",
-  "main": "src/core/index.js",
+  "description": "Adobe Experience Platform Web SDK",


jfkhoury · 2020-11-15T14:55:28Z

package.json

    }
  ],
  "dependencies": {
+    "css.escape": "^1.5.1",
+    "typescript": "^4.0.5",


Does that pull typescript into the library?

Oops, I didn't mean to add this as a dependency. Thanks for catching.

Aaronius

Thanks for moving this forward Jon. I left some comments that we should probably resolve.

README.md

Aaronius · 2020-11-19T03:18:23Z

README.md

+window.alloy("sendEvent", { ... });
+```
+
+The ES6 exports are exposed via the NPM "module" property, so you may need to adjust your rollup system to look for the module property.


"rollup system" should probably be "bundler" or "JavaScript bundler".

Couple questions here:

(1) Are you aware of any bundlers that don't support module by default? I'm aware it isn't standard, but I think it's been supported by default for 2+ years on the major bundlers. If so, this line may not be providing value and just introducing cognitive load, but who knows. If you keep it, it might be better to say something like "are exposed by the NPM package via the module field of its package.json, so you may...". If I'm a consumer having problems, that might give me more context for googling. 🤷‍♂️

(2) I'm trying to think through why we're creating main.js and modules.js as bundles. Normally what I've seen is that you would just run all the source code files through babel and dump all the resulting files into, say, an es5 directory, then point the main field in package.json to es5/index.js. For the es6 variant, you may just be able to point the module field in package.json to src/index.js.

One of the benefits of not generating bundles for the npm package consumers is that if the consuming application already has a dependency that matches one of our dependencies, the final application bundle only needs to include the dependency code once. Currently, we only have a couple dependencies, so that chance is somewhat low, but that may grow over time

One effect of taking this approach is that the extension will need to do some bundling before getting packaged and uploaded. But, I believe this would mean that you would be able to move the Launch core module dependencies from peerDependencies back to dependencies in this repo. When you do the bundling for the extension, I believe you'd just mark Launch core module dependencies as "externals" so that Launch can provide them instead of bundling them in from node_modules.

Sorry, I should've thought through this during my previous review as it definitely affects what I was saying in https://github.com/adobe/alloy/pull/632/files#r518529523.

Aaronius · 2020-11-19T03:20:24Z

README.md

+## Installation
+
+There are three supported ways to use Alloy.
+  1. Using Adobe Launch, install the Adobe Experience Platform Web SDK Extension.


Technically we should change "Adobe Launch" to "Adobe Experience Platform Launch" and remove "the" from before "Adobe Experience Platform Web SDK". We should probably lowercase "Extension" because "Adobe Experience Platform Web SDK Extension" isn't a brand itself and "Extension" alone isn't a pronoun.

Aaronius · 2020-11-19T03:21:48Z

README.md

+  2. Use the pre-built, minified version available via a CDN. You could also self-host this version.
+  3. Use the NPM library which exports an ES6 module.
+
+### Using the launch extension


"launch" here is a secondary reference so it should probably be "Experience Platform Launch" (my understanding is we can can drop the "Adobe" on secondary references).

Aaronius · 2020-11-19T03:26:36Z

README.md

+
+### Using the launch extension
+
+For documentation on the AEP Web SDK Launch Extension see the [launch documentation](https://docs.adobe.com/content/help/en/launch/using/extensions-ref/adobe-extension/aep-extension/overview.html)


Lowercase "Extension" and change "launch" to "Experience Platform Launch".

Aaronius · 2020-11-19T03:27:40Z

README.md

+
+For documentation on the AEP Web SDK Launch Extension see the [launch documentation](https://docs.adobe.com/content/help/en/launch/using/extensions-ref/adobe-extension/aep-extension/overview.html)
+
+### Using the stand alone version


"standalone" is one word.

Aaronius · 2020-11-19T03:39:58Z

README.md

+
+The ES6 exports are exposed via the NPM "module" property, so you may need to adjust your rollup system to look for the module property.
+
+


I still think all this documentation should be consolidated into the user docs like I mentioned in #632 (comment). It sounds like you might disagree, but you did mention you were considering at least trimming down this readme to the es6 installation instructions.

src/baseCode/index.js

test/unit/specs/components/EventMerge/createComponent.spec.js

jonsnyder · 2020-12-16T21:59:18Z

@Aaronius can you take another look at this PR?

jonsnyder · 2021-01-05T22:42:48Z

@Aaronius can you take another look at this PR? I implemented the createInstance method like you suggested in the docs PR.

Aaronius

I like.

Aaronius · 2021-01-06T17:42:28Z

src/index.js

+export default instanceName => {
+  const { executeCommand: instance, logger } = createExecuteCommand(
+    instanceName
+  );


Do you think it would make more sense to create the "log controller" here and pass it into createExecuteCommand rather than creating the log controller inside createExecuteCommand and exporting logger?

Aaronius · 2021-01-06T19:05:36Z

test/unit/specs/core/createInstanceFunction.spec.js

@@ -10,7 +10,7 @@ OF ANY KIND, either express or implied. See the License for the specific languag
 governing permissions and limitations under the License.
 */

-import createInstance from "../../../../src/core/createInstance";
+import createInstance from "../../../../src/core/createInstanceFunction";


You probably want to rename createInstance to createInstanceFunction here.

jonsnyder · 2021-01-19T21:25:41Z

package.json

@@ -68,6 +74,8 @@
    "uuid": "^3.3.2"
  },
  "devDependencies": {
+    "@adobe/alloy": "file:./",


For now this just references the current directory, but when we publish the NPM library I will change this to reference the actual version.

…to work" This reverts commit a5e7a39.

jfkhoury

Great work @jonsnyder !!

I recommend testing the built library manually in the sandbox since there's so many changes :)

jonsnyder added 8 commits October 12, 2020 14:42

CORE-52172 expose ES modules so Launch extension can consume npm repo

5548e15

CORE-52172 add tests and ignores, add more terser options

8cdcc34

CORE-52172 add readme

fdf619f

Merge remote-tracking branch 'origin/master' into npmLibrary

ca0139e

CORE-52172 add test files to pass lint test

f4f37ba

CORE-52172 finish readme, setup files array, fix terser options

6213606

Merge remote-tracking branch 'origin/main' into npmLibrary

6cc1416

expose es6 and commonjs modules, address PR comments

9b459e2

jfkhoury reviewed Nov 15, 2020

View reviewed changes

Aaronius reviewed Nov 19, 2020

View reviewed changes

jonsnyder added 2 commits November 30, 2020 10:23

Remove typescript from package.json

c48cc80

Fix event merge id issue

ca0892a

jonsnyder force-pushed the npmLibrary branch from 7e32b97 to ca0892a Compare November 30, 2020 17:27

jonsnyder added 8 commits November 30, 2020 14:31

Make the generated baseCode identical to pre-npm library version

8e34421

Do not rollup es5 and es6 verions

41fcfda

update babel/cli version

821977d

Add rimraf

ccbbef9

Use rimraf directly in prepublish script

922bb03

Remove installation instructions from github README

a2a9893

CORE-52500 remove 'the' in Readme, remove jscc dependency

dda91a0

Merge remote-tracking branch 'origin/main' into npmLibrary

a46c2d4

jonsnyder added 2 commits January 5, 2021 15:26

Merge remote-tracking branch 'origin/main' into npmLibrary

3ce8902

expose a createInstance function rather than core and baseCode

f4c5646

Aaronius approved these changes Jan 6, 2021

View reviewed changes

jonsnyder added 3 commits January 15, 2021 15:54

Add functional test for NPM library

d54c472

Merge remote-tracking branch 'origin/main' into npmLibrary

0b5b65d

Remove wait for globalFunction in npmLibrary test

eb9e8f7

jonsnyder added 3 commits January 15, 2021 17:06

Rename createInstance in test

52e5fee

Merge remote-tracking branch 'origin/main' into npmLibrary

d18dc14

Use NPM Library in prod for integration tests

f5f7c57

jonsnyder commented Jan 19, 2021

View reviewed changes

jonsnyder added 2 commits January 21, 2021 09:47

explicitly include index in imports to allow Launch packager to work

a5e7a39

Revert "explicitly include index in imports to allow Launch packager …

ff5b019

…to work" This reverts commit a5e7a39.

jonsnyder force-pushed the npmLibrary branch from c848efa to ff5b019 Compare January 21, 2021 16:48

jonsnyder added 4 commits January 22, 2021 13:23

rename build folders and files

b8eb968

update package-lock.json

f008c43

Remove npmPackageProd until npm package is deployed

55d7cd3

Fix build to output the baseCode

acf533f

jonsnyder requested review from liljenback and shammowla January 23, 2021 00:17

jfkhoury approved these changes Jan 27, 2021

View reviewed changes

fix rollup for sandbox

345ba85

jonsnyder merged commit 2bee677 into main Jan 28, 2021

jonsnyder deleted the npmLibrary branch January 28, 2021 16:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Get ready to publish Alloy as an NPM repo #637

Get ready to publish Alloy as an NPM repo #637

jonsnyder commented Nov 13, 2020

jfkhoury Nov 15, 2020

jfkhoury Nov 15, 2020

jonsnyder Nov 16, 2020

Aaronius left a comment

Aaronius Nov 19, 2020

Aaronius Nov 19, 2020

Aaronius Nov 19, 2020

Aaronius Nov 19, 2020

Aaronius Nov 19, 2020

Aaronius Nov 19, 2020

Aaronius Nov 19, 2020

jonsnyder commented Dec 16, 2020

jonsnyder commented Jan 5, 2021

Aaronius left a comment

Aaronius Jan 6, 2021

Aaronius Jan 6, 2021

jonsnyder Jan 19, 2021

jfkhoury left a comment


		### Using the launch extension

		For documentation on the AEP Web SDK Launch Extension see the [launch documentation](https://docs.adobe.com/content/help/en/launch/using/extensions-ref/adobe-extension/aep-extension/overview.html)


		For documentation on the AEP Web SDK Launch Extension see the [launch documentation](https://docs.adobe.com/content/help/en/launch/using/extensions-ref/adobe-extension/aep-extension/overview.html)

		### Using the stand alone version


		The ES6 exports are exposed via the NPM "module" property, so you may need to adjust your rollup system to look for the module property.

Get ready to publish Alloy as an NPM repo #637

Get ready to publish Alloy as an NPM repo #637

Conversation

jonsnyder commented Nov 13, 2020

Description

Related Issue

Motivation and Context

Screenshots (if appropriate):

Types of changes

Checklist:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Aaronius left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonsnyder commented Dec 16, 2020

jonsnyder commented Jan 5, 2021

Aaronius left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jfkhoury left a comment

Choose a reason for hiding this comment