feat: add `ParagonWebpackPlugin` to support design tokens #546

dcoa · 2024-05-17T05:08:32Z

Description:

This PR updates the original one #365 closer to the master branch and adds some extra tests.

Please read the original PR for additional context.

Changes

Delete Runtime Configuration reference: My reason for making this change is the nature of runtime configuration, which can override any configuration defined previously. The plugin runs during the build time and we have env.config.js that can set the variables. (let me know if my reasoning is correct)
Update @edx/paragon to @openedx/paragon and add compatibility for either @edx/brand or @openedx/brand

Finally, I would like to split this PR in 2 one for the main implementation and another one for the example app (due to this one adds frontend-platform and paragon)

openedx-webhooks · 2024-05-17T05:08:37Z

Thanks for the pull request, @dcoa!

What's next?

Please work through the following steps to get your changes ready for engineering review:

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
- This process (including the steps you'll need to take) is documented here.
If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

Dependencies

This PR must be merged before / after / at the same time as ...
Blockers

This PR is waiting for OEP-1234 to be accepted.
Timeline information

This PR must be merged by XX date because ...
Partner information

This is for a course on edx.org.
Supporting documentation
Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

🔘 Let us know that your PR is ready for review:

Who will review my changes?

This repository is currently maintained by @openedx/committers-frontend-build. Tag them in a comment and let them know that your changes are ready for review.

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

The size and impact of the changes that it introduces
The need for product review
Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

itsjeyd · 2024-05-23T15:34:59Z

Hey @dcoa, thank you for this contribution! Please let us know when the changes are ready for review.

PKulkoRaccoonGang

@dcoa Thank you for re-opening and improving this PR! Left a few suggestions

PKulkoRaccoonGang · 2024-05-27T08:49:58Z

lib/plugins/paragon-webpack-plugin/utils.js

@@ -0,0 +1,373 @@
+const { sources } = require('webpack');


[proposal]: This file is quite large. I suggest dividing it into several files and creating a folder with utilities. I think it would be a good idea to follow this structure:

./utils

htmlUtils.js

getDescendantByTag

findScriptInsertionPoint

findStylesheetInsertionPoint

scriptUtils.js

minifyScript

insertScriptContentsIntoDocument

stylesheetUtils.js

insertStylesheetsIntoDocument

assetUtils.js

findCoreCssAsset

findThemeVariantCssAssets

getCssAssetsFromCompilation

scriptContentUtils.js

addToScriptContents

generateScriptContents

urlUtils.js

handleVersionSubstitution

getParagonStylesheetUrls

I agree and I did, not the same order but let me know what you think :)

Thank you! This looks great 💯

config/data/paragonUtils.js

lib/plugins/paragon-webpack-plugin/utils.js

config/data/paragonUtils.js

Alec4r · 2024-06-12T00:07:39Z

config/data/paragonUtils.js

+  if (!fs.existsSync(pathToPackageJson)) {
+    return undefined;
+  }
+  return JSON.parse(fs.readFileSync(pathToPackageJson)).version;


should we add the second argument to use utf8?

This is optional, however, after reading some posts about it I think it's a good suggestion. 👍

Alec4r · 2024-06-12T00:13:14Z

config/data/paragonUtils.js

+  const {
+    core: themeCore,
+    variants: themeVariants,
+    defaults,
+  } = paragonConfig?.themeUrls || {};
+


should we validate if the values exist before use them?, I mean just to avoid future errors, something like if !themeCore || !themeVariants return undefined.

It's not necessary because we are using destructuring if any of them is not defined that will return undefined by default.

Alec4r · 2024-06-12T00:17:54Z

config/data/paragonUtils.js

+  const themeVariantResults = {};
+  validThemeVariantPaths.forEach(([themeVariant, value]) => {
+    themeVariantResults[themeVariant] = {
+      filePath: path.resolve(dir, 'node_modules', npmPackageName, 'dist', value.paths.minified),
+      entryName: isBrandOverride ? `brand.theme.variants.${themeVariant}` : `paragon.theme.variants.${themeVariant}`,
+      outputChunkName: isBrandOverride ? `brand-theme-variants-${themeVariant}` : `paragon-theme-variants-${themeVariant}`,
+    };
+  });


I think we could use .reduce instead of filtering and iterate this, it might be more efficient but I think this is an easier way to read the code.

Should we worry about efficiency?

Alec4r · 2024-06-12T00:24:11Z

config/data/paragonUtils.js

+  if (!paragonThemeCss) {
+    return cacheGroups;
+  }
+  cacheGroups[paragonThemeCss.core.outputChunkName] = {


We could remove the line 107 and just define the constant from here, right?

itsjeyd · 2024-07-18T15:13:34Z

@dcoa We've got a green build here and it's been a while since the last update. So I'm assuming that the changes are ready for engineering review. Let me know if that's not the case.

dcoa · 2024-07-21T12:05:05Z

Hi @itsjeyd yes, it is ready for review and has been tested alongside other design tokens PRs here openedx/frontend-app-discussions#726

itsjeyd · 2024-07-25T09:14:49Z

Thanks for confirming @dcoa.

@brian-smith-tcril @adamstankiewicz Would you be able to have a look at this PR?

…upported

brian-smith-tcril · 2024-08-02T15:09:07Z

@dcoa in https://openedx.slack.com/archives/C071U9E4VNV/p1715966767660459?thread_ts=1715940913.033459&cid=C071U9E4VNV I mentioned

I'd prefer to move over to using @openedx/brand-openedx everywhere but I don't remember all of the gotchas/blockers around that. I think moving forward we should try to use @openedx but if we run into conflicts because of it we can alias back to @edx and note why that was required in any given instance.

When I wrote that I wasn't thinking about landing this PR as a non breaking change. Since the plan now is to land this as a non breaking change I think that fully justifies keeping the @edx namespace for now.

I would still like to make the move to the @openedx namespace, but since doing so is a breaking change I feel it would be better off as a separate PR so as to not delay the merge of this one.

adamstankiewicz · 2024-08-02T15:14:26Z

Thanks @brian-smith-tcril. Only thing I'd add regarding the brand package scope (@edx/brand vs. @openedx/brand) is that I think it might make sense to handle either scope so we are compatible with the current state of MFEs' usage with @edx/brand, but also be forward-looking knowing we will migrate to @openedx/brand eventually. Once we're confident consumers/instances have fully migrated to @openedx/brand, we could come back to remove the @edx/brand at that point. Supporting both scopes now would eliminate the need for any coordinated effort in adding support for @openedx/brand down the road.

brian-smith-tcril · 2024-08-09T15:39:07Z

lib/plugins/paragon-webpack-plugin/ParagonWebpackPlugin.js

+   * 1. ``envConfig.PARAGON_THEME_URLS`` (JS based)
+   * 3. ``process.env.PARAGON_THEME_URLS`` (JSON based)


I feel like having PARAGON_THEME_URLS work in an env.config.js file but not an env.config.jsx file is more confusing than just saying PARAGON_THEME_URLS must be set as an environment variable.

I'd love to hear what others think about this!

To be clear - this file cannot import or use env.config with any file extension, and we must use process.env to get this value. The env.config file is runtime configuration and is expected to import runtime files that will require transpilation (i.e., jsx/tsx) and depend on their own runtime dependencies. That code can't meaningfully pollute the build-time configuration, and having multiple files named env.config with different extensions would be seriously confusing for folks.

At a later date we may decide to create a new type of build-only configuration file, but we're just not there at the moment. For now, we just need to use process.env either via command line environment variables or the .env files, and it'll come in as a string we need to JSON.parse.

Furthermore, worse, would be for build-time code and build-time dependencies to find their way into env.config... that would mean build-time code gets bundled with the app for a browser environment which is a huge no-no and would definitely break.

+1. Agreed, we should only be relying on process.env.PARAGON_THEME_URLS at this point, with JSON.parse for the build-time vs. runtime configuration that @davidjoy is alluding to above (across both this frontend-build PR and within frontend-platform).

On the runtime side for frontend-platform's use, by all means copy PARAGON_THEME_URLS into env.config and format it nicely as an actual object instead of a string. But for now it does need to be duplicated, unfortunately, because the two types of config can't mingle.

I gave a couple of thumbs up above, but better to be explicit: I agree that for now, process.env.PARAGON_THEME_URLS should be what is used, and only that.

I also like the idea of eventually having a separate build-only config file, thus doing away with any potential for confusion or breakage. (While at the same time finally removing support for the .env files, hopefully.)

I also like the idea of eventually having a separate build-only config file, thus doing away with any potential for confusion or breakage. (While at the same time finally removing support for the .env files, hopefully.)

💯

That lines up perfectly with the feelings expressed in the slack thread.

Done 😁 @adamstankiewicz @brian-smith-tcril

adamstankiewicz

LGTM Great job! I also closed the original POC implementation's PR.

brian-smith-tcril

Thank you so much for this! I know a long review process full of in-depth discussions around architectural decisions isn't always the most fun when trying to land a PR, but this came out great!

LGTM!

openedx-webhooks · 2024-08-13T21:21:32Z

@dcoa 🎉 Your pull request was merged! Please take a moment to answer a two question survey so we can improve your experience in the future.

openedx-semantic-release-bot · 2024-08-13T21:22:51Z

🎉 This PR is included in version 14.1.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

openedx-semantic-release-bot · 2024-08-13T21:23:12Z

🎉 This PR is included in version 15.0.0-alpha.15 🎉

The release is available on:

Your semantic-release bot 📦🚀

davidjoy · 2024-09-12T15:33:52Z

I had a comment here about using default as a key name, but I think it's actually fine.

openedx-webhooks added the open-source-contribution PR author is not from Axim or 2U label May 17, 2024

dcoa changed the title ~~Dcoa/design tokens support~~ feat: expose PARAGON as a global variable May 17, 2024

dcoa force-pushed the dcoa/design-tokens-support branch 2 times, most recently from 86312c3 to 9c1a27b Compare May 17, 2024 09:05

dcoa requested review from brian-smith-tcril and adamstankiewicz May 17, 2024 09:51

dcoa marked this pull request as ready for review May 17, 2024 09:55

itsjeyd added the core contributor PR author is a Core Contributor (who may or may not have write access to this repo). label May 23, 2024

dcoa mentioned this pull request May 24, 2024

Finalize work on PR 440 (https://github.com/openedx/frontend-platform/pull/440) openedx/paragon#3061

Open

PKulkoRaccoonGang reviewed May 27, 2024

View reviewed changes

dcoa mentioned this pull request May 28, 2024

feat: add example changes for test ParagonPlugin #549

Closed

dcoa force-pushed the dcoa/design-tokens-support branch from afc31ac to 29f0831 Compare May 29, 2024 09:43

dcoa mentioned this pull request May 30, 2024

Finalize work on paragon 23 support at frontend-build (openedx/frontend-build/pull/365) openedx/paragon#3062

Open

PKulkoRaccoonGang reviewed May 31, 2024

View reviewed changes

config/data/paragonUtils.js Outdated Show resolved Hide resolved

PKulkoRaccoonGang mentioned this pull request May 31, 2024

feat: adds support for loading external theme CSS for MFEs openedx/frontend-platform#689

Open

4 tasks

Alec4r reviewed Jun 12, 2024

View reviewed changes

dcoa force-pushed the dcoa/design-tokens-support branch from 9c54792 to dd5647e Compare June 26, 2024 02:19

itsjeyd added the waiting for eng review PR is ready for review. Review and merge it, or suggest changes. label Jul 18, 2024

refactor: remove process.env references in ParagonWebpackPlugin, no s…

347e820

…upported

dcoa force-pushed the dcoa/design-tokens-support branch from 2733312 to 347e820 Compare August 2, 2024 04:48

fix: use openedx scope for webpack.dev.config

c019cc9

itsjeyd added waiting on author PR author needs to resolve review requests, answer questions, fix tests, etc. and removed waiting for eng review PR is ready for review. Review and merge it, or suggest changes. labels Aug 2, 2024

dcoa force-pushed the dcoa/design-tokens-support branch from 05b69a2 to 7c65744 Compare August 4, 2024 10:02

fix: allow processing edx and openedx brand scope

182100f

dcoa force-pushed the dcoa/design-tokens-support branch from 7c65744 to 182100f Compare August 4, 2024 10:18

itsjeyd added waiting for eng review PR is ready for review. Review and merge it, or suggest changes. and removed waiting on author PR author needs to resolve review requests, answer questions, fix tests, etc. labels Aug 8, 2024

itsjeyd requested a review from adamstankiewicz August 8, 2024 06:39

refactor: support process.env.PARAGON_THEME_URLS

516c1bf

brian-smith-tcril reviewed Aug 9, 2024

View reviewed changes

fix: make PARAGON_THEME_URLS be defined only as env

27d0f75

adamstankiewicz mentioned this pull request Aug 13, 2024

feat: adds support for loading external theme CSS for MFEs openedx/frontend-platform#440

Closed

4 tasks

adamstankiewicz approved these changes Aug 13, 2024

View reviewed changes

brian-smith-tcril approved these changes Aug 13, 2024

View reviewed changes

brian-smith-tcril changed the title ~~feat: expose PARAGON as a global variable~~ feat: add ParagonWebpackPlugin to support design tokens Aug 13, 2024

brian-smith-tcril merged commit 031f51f into openedx:master Aug 13, 2024
5 checks passed

openedx-semantic-release-bot added the released label Aug 13, 2024

openedx-semantic-release-bot added the released on @alpha label Aug 13, 2024

This was referenced Aug 30, 2024

fix: ensure webpack.dev.config.js includes quietDeps: true, applies injected <link> styles once loaded, example app updates to show ParagonWebpackPlugin output #584

Merged

feat: expose PARAGON as a global variable #365

Closed

itsjeyd removed the waiting for eng review PR is ready for review. Review and merge it, or suggest changes. label Sep 7, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add `ParagonWebpackPlugin` to support design tokens #546

feat: add `ParagonWebpackPlugin` to support design tokens #546

dcoa commented May 17, 2024 •

edited

Loading

openedx-webhooks commented May 17, 2024 •

edited

Loading

itsjeyd commented May 23, 2024

PKulkoRaccoonGang left a comment

PKulkoRaccoonGang May 27, 2024

dcoa May 29, 2024 •

edited

Loading

PKulkoRaccoonGang May 29, 2024

Alec4r Jun 12, 2024

dcoa Jun 17, 2024

Alec4r Jun 12, 2024

dcoa Jun 17, 2024

Alec4r Jun 12, 2024

Alec4r Jun 12, 2024

itsjeyd commented Jul 18, 2024

dcoa commented Jul 21, 2024

itsjeyd commented Jul 25, 2024

brian-smith-tcril commented Aug 2, 2024

adamstankiewicz commented Aug 2, 2024

brian-smith-tcril Aug 9, 2024

davidjoy Aug 9, 2024

davidjoy Aug 9, 2024

adamstankiewicz Aug 9, 2024

davidjoy Aug 9, 2024

arbrandes Aug 9, 2024

brian-smith-tcril Aug 9, 2024

dcoa Aug 10, 2024 •

edited

Loading

adamstankiewicz left a comment •

edited

Loading

brian-smith-tcril left a comment

openedx-webhooks commented Aug 13, 2024

openedx-semantic-release-bot commented Aug 13, 2024

openedx-semantic-release-bot commented Aug 13, 2024

davidjoy commented Sep 12, 2024

		* 1. ``envConfig.PARAGON_THEME_URLS`` (JS based)
		* 3. ``process.env.PARAGON_THEME_URLS`` (JSON based)

feat: add ParagonWebpackPlugin to support design tokens #546

feat: add ParagonWebpackPlugin to support design tokens #546

Conversation

dcoa commented May 17, 2024 • edited Loading

openedx-webhooks commented May 17, 2024 • edited Loading

What's next?

🔘 Get product approval

🔘 Provide context

🔘 Get a green build

🔘 Let us know that your PR is ready for review:

Who will review my changes?

Where can I find more information?

When can I expect my changes to be merged?

itsjeyd commented May 23, 2024

PKulkoRaccoonGang left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dcoa May 29, 2024 • edited Loading

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

itsjeyd commented Jul 18, 2024

dcoa commented Jul 21, 2024

itsjeyd commented Jul 25, 2024

brian-smith-tcril commented Aug 2, 2024

adamstankiewicz commented Aug 2, 2024

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

💯

dcoa Aug 10, 2024 • edited Loading

Choose a reason for hiding this comment

adamstankiewicz left a comment • edited Loading

Choose a reason for hiding this comment

brian-smith-tcril left a comment

Choose a reason for hiding this comment

openedx-webhooks commented Aug 13, 2024

openedx-semantic-release-bot commented Aug 13, 2024

openedx-semantic-release-bot commented Aug 13, 2024

davidjoy commented Sep 12, 2024

feat: add `ParagonWebpackPlugin` to support design tokens #546

feat: add `ParagonWebpackPlugin` to support design tokens #546

dcoa commented May 17, 2024 •

edited

Loading

openedx-webhooks commented May 17, 2024 •

edited

Loading

dcoa May 29, 2024 •

edited

Loading

dcoa Aug 10, 2024 •

edited

Loading

adamstankiewicz left a comment •

edited

Loading