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.

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

[EPIC] Better NPM package Bundle Layout with typescript definition bundle (.d.ts) #5854

Open
t83714 opened this issue Sep 24, 2021 · 4 comments
Assignees
Labels

Comments

@t83714
Copy link
Member

t83714 commented Sep 24, 2021

Better NPM package Bundle Layout with typescript definition bundle (.d.ts)

Background & Motivation

This PR demonstrated the difficulties that a terriajs lib / plugin developer might face when try to bundle a library / plugin that requires TerriaJs as dependencies.

Approach & Goals

This ticket proposes a new bundle layout approach that can achieve:

  • Zero (or minimum) "dependencies" in TerriaJs's package.json.
    • Thus, low impact & version interference when a developer add TerriaJs as a devDependencies or dependencies of his project.
    • Regarding how to achieve this, please refer to this PR and this ticket
  • The JS bundle will be produced by typescript (via rollup typescript plugin) with declaration tsconfig set to true to make sure all types are correct.
  • A seperate types definition bundle (.d.ts file) will be produced to include all TerriaJs types definition.
    • Developers do not need to import the "Source" version to gain typescript support for their own projects (that declare TerriaJs as dependencies).
      • a types field will be added to package.json to indicate the location of the .d.ts. See here. And example package here
  • Offer the following 3 JS bundle format in one npm pakcages:
    • cjs: common js bundle. For node js or any bundler doesn't support esm.
    • esm: es6 module bundle. For any bundler support esm & tree shaking.
    • umd: For loading via web browser <script> tags.

Please note: we will not attempt to support the package.json exports Fallbacks that available in node.js 13, as it's too new and the tools like yarn is not ready yet. e.g. this PR still in progress

What's Next & How to achieve it

This will be a task too big to achieve in one go (we might want to convert it into an epic if go ahead). However, I think it's possible seperate it into smaller tasks that can be gradually done, review & merged WITHOUT creating backwards compatibility issues for developers & users.

Here is the plan:

  • Step 1: Leave the bundle layout as it is but make it build using typescript (rather than babel typescript plugin) **WITH ** declaration tsconfig set to true.
    • This might require code changes in order to fix existing types issues.
  • Step 2: Go through dependencies list in package.json and make decision of how to handle the dependencies based on the 3 options mentioned in my PR. i.e.:
    • Move to devDependencies & peerDependencies, excluded it from bundle and import it as "external"
    • Move to devDependencies, included in the bundle
    • Leave it in dependencies, excluded it from bundle and import it as "external"
  • Step 3: Write rollup config & script to implement the new JS bundle layout.
  • Step 4: Use Microsoft's api-extractor to rollup / bundle all (.d.ts) files. See example here

Side note re: Build Speed

typescript is known to be slow for building large project.
Babel won't be the solution --- it might be fast but it simply strip the types without understanding it.
People often solve it by sub projects / mono repo --- i.e. you only need to build the module you've modified without building everything.
Since ts 3.7, we have the project reference feature provided better support to it --- Magda actually use this feature. See here.
Having said that, it's complicated to introduce sub-project event with ts project reference feature. We'd better get this ticket done before solving the build speed issue.

@t83714
Copy link
Member Author

t83714 commented Sep 29, 2021

I created a PR here: #5863 to highlight the problem we have for step 1 --- in order to output types (.d.ts) files

@wibily
Copy link
Contributor

wibily commented Oct 13, 2021

Nanda to review, discuss with Jacky and break it down into smaller issues (possibly in an epic)

@t83714
Copy link
Member Author

t83714 commented Nov 23, 2021

We also need to review all babel plugins usage here:
https://github.com/TerriaJS/terriajs/blob/main/buildprocess/configureWebpack.js
Especially, string-replace-loader & babel-plugin-jsx-control-statements.
Depending on how we design our lib layout, we might not need some of them.
For the rest of the plugin usage, we need to decide either:

  • remove the usage from the current codebase
  • Or find/recreate an alternative plugin for rollup

@tephenavies
Copy link
Member

tephenavies commented Feb 9, 2022

babel-plugin-jsx-control-statements should be phased out (no TSX support) and string-replace-loader + superGet is holding us back from switching to emitting es6 with generators. Maybe we'll replace all calls to super.reactiveProperty with getSuperReactiveProperty(super, "reactiveProperty").

To build TerriaMap to es6 with generators use e.g. "browserslist": "last 3 years and supports es6-generators" in package.json.

@AnaBelgun AnaBelgun changed the title Better NPM package Bundle Layout with typescript definition bundle (.d.ts) [EPIC] Better NPM package Bundle Layout with typescript definition bundle (.d.ts) Jan 10, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

5 participants