Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Get ready to publish Alloy as an NPM repo #637

Merged
merged 33 commits into from
Jan 28, 2021
Merged

Get ready to publish Alloy as an NPM repo #637

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
5548e15
CORE-52172 expose ES modules so Launch extension can consume npm repo
jonsnyder Oct 8, 2020
8cdcc34
CORE-52172 add tests and ignores, add more terser options
jonsnyder Oct 12, 2020
fdf619f
CORE-52172 add readme
jonsnyder Oct 14, 2020
ca0139e
Merge remote-tracking branch 'origin/master' into npmLibrary
jonsnyder Nov 2, 2020
f4f37ba
CORE-52172 add test files to pass lint test
jonsnyder Nov 2, 2020
6213606
CORE-52172 finish readme, setup files array, fix terser options
jonsnyder Nov 3, 2020
6cc1416
Merge remote-tracking branch 'origin/main' into npmLibrary
jonsnyder Nov 13, 2020
9b459e2
expose es6 and commonjs modules, address PR comments
jonsnyder Nov 13, 2020
c48cc80
Remove typescript from package.json
jonsnyder Nov 16, 2020
ca0892a
Fix event merge id issue
jonsnyder Nov 30, 2020
8e34421
Make the generated baseCode identical to pre-npm library version
jonsnyder Nov 30, 2020
41fcfda
Do not rollup es5 and es6 verions
jonsnyder Dec 1, 2020
821977d
update babel/cli version
jonsnyder Dec 8, 2020
ccbbef9
Add rimraf
jonsnyder Dec 8, 2020
922bb03
Use rimraf directly in prepublish script
jonsnyder Dec 8, 2020
a2a9893
Remove installation instructions from github README
jonsnyder Dec 16, 2020
dda91a0
CORE-52500 remove 'the' in Readme, remove jscc dependency
jonsnyder Dec 16, 2020
a46c2d4
Merge remote-tracking branch 'origin/main' into npmLibrary
jonsnyder Dec 16, 2020
3ce8902
Merge remote-tracking branch 'origin/main' into npmLibrary
jonsnyder Jan 5, 2021
f4c5646
expose a createInstance function rather than core and baseCode
jonsnyder Jan 5, 2021
d54c472
Add functional test for NPM library
jonsnyder Jan 15, 2021
0b5b65d
Merge remote-tracking branch 'origin/main' into npmLibrary
jonsnyder Jan 15, 2021
eb9e8f7
Remove wait for globalFunction in npmLibrary test
jonsnyder Jan 15, 2021
52e5fee
Rename createInstance in test
jonsnyder Jan 16, 2021
d18dc14
Merge remote-tracking branch 'origin/main' into npmLibrary
jonsnyder Jan 19, 2021
f5f7c57
Use NPM Library in prod for integration tests
jonsnyder Jan 19, 2021
a5e7a39
explicitly include index in imports to allow Launch packager to work
jonsnyder Jan 20, 2021
ff5b019
Revert "explicitly include index in imports to allow Launch packager …
jonsnyder Jan 21, 2021
b8eb968
rename build folders and files
jonsnyder Jan 22, 2021
f008c43
update package-lock.json
jonsnyder Jan 22, 2021
55d7cd3
Remove npmPackageProd until npm package is deployed
jonsnyder Jan 22, 2021
acf533f
Fix build to output the baseCode
jonsnyder Jan 23, 2021
345ba85
fix rollup for sandbox
jonsnyder Jan 28, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 49 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,56 @@

# Alloy

Alloy is the code name for the Adobe Experience Platform Web SDK. It allows for streaming data into the platform, syncing identities, personalizing content, and more.
Alloy is the code name for the Adobe Experience Platform Web SDK. It allows for recording events into the Adobe Experience Platform, syncing identities, personalizing content, and more.
jonsnyder marked this conversation as resolved.
Show resolved Hide resolved

For documentation on how to use Alloy, please see the [user documentation](https://adobe.ly/36dGGp6).

For documentation on how to contribute to Alloy, please see the [developer documentation](https://github.com/adobe/alloy/wiki).

## Installation

There are three supported ways to use Alloy.
1. Using Adobe Launch, install the Adobe Experience Platform Web SDK Extension.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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).


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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


### Using the stand alone version
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"standalone" is one word.


```html
<script>
!function(n,o){o.forEach(function(o){n[o]||((n.__alloyNS=n.__alloyNS||
[]).push(o),n[o]=function(){var u=arguments;return new Promise(
function(i,l){n[o].q.push([i,l,u])})},n[o].q=[])})}
(window,["alloy"]);
</script>
<script src="https://cdn1.adoberesources.net/alloy/2.2.0/alloy.min.js" async></script>
<script>
window.alloy("config", { ... });
window.alloy("sendEvent", { ... });
</script>
```

### Using the NPM library

```bash
npm install @adobe/alloy
```

Using the library:

```javascript
import { baseCode, core } from "@adobe/alloy";
baseCode(["alloy"]); // creates the window.alloy function
core(); // runs

window.alloy("config", { ... });
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.



Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

8 changes: 7 additions & 1 deletion coverageignore.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,4 +14,10 @@ governing permissions and limitations under the License.
* Patterns of source files (files within the src directory) that should be
* ignored for test coverage checks and reporting.
*/
module.exports = ["**/.*", "**/constants/**", "**/index.js"];
module.exports = [
"**/.*",
"**/constants/**",
"**/index.js",
"baseCode.js",
"standalone.js"
];
60 changes: 37 additions & 23 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

30 changes: 21 additions & 9 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Finally :)

"main": "dist/main.js",
"module": "dist/module.js",
"files": [
"dist/main.js",
"dist/module.js"
],
"scripts": {
"install": "cd sandbox && npm install",
"clean": "rimraf dist",
Expand All @@ -13,13 +18,13 @@
"test:unit:watch": "karma start",
"test:unit:saucelabs": "karma start karma-saucelabs.conf.js",
"test:unit:coverage": "karma start --single-run --reporters spec,coverage",
"test:functional": "rollup -c --environment BUILD:prodStandalone && EDGE_BASE_PATH=\"ee-pre-prd\" ALLOY_ENV=\"int\" testcafe chrome",
"test:functional:watch": "EDGE_BASE_PATH=\"ee-pre-prd\" ALLOY_ENV=\"int\" BUILD=\"prodStandalone\" ./scripts/watchFunctionalTests.js",
"test:functional": "rollup -c --environment BUILD:prod && EDGE_BASE_PATH=\"ee-pre-prd\" ALLOY_ENV=\"int\" testcafe chrome",
"test:functional:watch": "EDGE_BASE_PATH=\"ee-pre-prd\" ALLOY_ENV=\"int\" BUILD=\"prod\" ./scripts/watchFunctionalTests.js",
"test:functional:ci": "EDGE_BASE_PATH=\"ee-pre-prd\" ALLOY_ENV=\"int\" testcafe chrome && EDGE_BASE_PATH=\"ee-pre-prd\" ALLOY_ENV=\"int\" testcafe 'browserstack:ie@11:Windows 10'",
"test:functional:cron:prod": "ALLOY_ENV=\"prod\" testcafe chrome",
"test:functional:api": "testcafe chrome:headless",
"dev": "concurrently --names build,sandbox \"rollup -c -w\" \"cd sandbox && export REACT_APP_NONCE=321 && npm start\"",
"build": "npm run format && npm run lint && npm run clean && concurrently \"rollup -c --environment BUILD:prodStandalone\" \"rollup -c --environment MINIFY,BUILD:prodStandalone\" \"rollup -c --environment BUILD:prodReactor\" && echo \"Base Code:\" && terser src/baseCode/index.js --mangle --compress unused=false",
"build": "npm run format && npm run lint && npm run clean && concurrently \"rollup -c --environment BUILD:prod\" \"rollup -c --environment MINIFY,BUILD:prod\" && echo \"Base Code:\" && cat dist/baseCode.min.js",
"checkthattestfilesexist": "./scripts/checkThatTestFilesExist.js"
},
"husky": {
Expand Down Expand Up @@ -53,18 +58,25 @@
"license": "Apache-2.0",
"bundlesize": [
{
"path": "./dist/standalone/alloy.min.js"
"path": "./dist/alloy.min.js"
}
],
"dependencies": {
"css.escape": "^1.5.1",
"typescript": "^4.0.5",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does that pull typescript into the library?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

"uuid": "^3.3.2"
},
"peerDependencies": {
"@adobe/reactor-cookie": "^1.0.0",
"@adobe/reactor-load-script": "^1.1.1",
"@adobe/reactor-object-assign": "^1.0.0",
"@adobe/reactor-query-string": "^1.0.0",
"css.escape": "^1.5.1",
"uuid": "^3.3.2"
"@adobe/reactor-query-string": "^1.0.0"
},
"devDependencies": {
"@adobe/reactor-cookie": "^1.0.0",
"@adobe/reactor-load-script": "^1.1.1",
"@adobe/reactor-object-assign": "^1.0.0",
"@adobe/reactor-query-string": "^1.0.0",
"@babel/core": "^7.2.2",
"@babel/plugin-proposal-object-rest-spread": "^7.3.2",
"@babel/plugin-transform-template-literals": "^7.4.4",
Expand Down
Loading