chore: improve the configuration to build the npm package #87

tbouffard · 2022-05-09T16:10:31Z

Root and all package.json files

Fix license, version and authors
Remove the non-relevant .npmignore file at the project. It was designed for mxgraph, the whole directory structure
changed, and we don't plan to publish the root package

core package

Generate type definition and javascript files for ESM output
- dedicated folder for esm and types in the dist folder to clearly separate concerns
- exported in the package.json
Add npm script for npm pack configuration
Drop the postinstall npm script that built the core bundle. It would have been run when the package is installed
in dependent projects at dependencies install. And it would have failed as it tries to build the project from TypeScript
sources that are not available in the npm package.

fix: ConstraintHandler now loads image as everywhere else in the code using Client.imageBasePath
Using import doesn't work as the image is not available in the npm package. It generated error like this in ViteJS
project:
Failed to resolve import "../../../images/point.gif" from "../core/dist/esm/view/handler/ConstraintHandler.js". Does the file exist?
This gif import had been introduced to make Anchors.stories.js retrieve the gif file. Configuring imageBasePath as
already done in other stories fixes the issue.

Don't export EditorCodec and StylesheetCodec as they generate errors.
This is a temporary solution to avoid error in dependent project (at least, with ViteJS projects).

closes #84

Notes

This contribution is done under the terms of the Apache 2.0 license as stated in https://www.apache.org/licenses/LICENSE-2.0.

How to use

Run

from the project root: npm install
then, from the core package: npm pack
you can finally use the core folder or the package tgz file in an external project (using npm link or npm install)

Testing project

This Pull Request initially add a TypeScript integration example built with ViteJS.
It allows testing the maxgraph core npm package in a TypeScript project. This ensures that the types and the esm code is correctly configured in the package and available for integration.
I don't know if we should keep this project in the repository or if it deserves its own repository. Feel free to comment about it.

About the gif import removal

The gif import was introduced to fix the Anchors example in b2bb10e#diff-1ef320fff9bb7fc4d6aa19a32348357901420e1724b8288d9a22f1f51fad34cc
Restoring the original Client.imageBasePath usage only required to configure the value in the story.

Commented exports

EditorCodec and StylesheetCodec are no more exported. I will test the package with a Rollup project and probably with other build tools/bundlers to see if they have issues when these 2 classes are exported.
In the meantime, if you find a way to restore the exports, feel free to comment.

Root and all package.json files - Fix license, version and authors - Remove the non-relevant .npmignore file at the project. It was designed for mxgraph, the whole directory structure changed, and we don't plan to publish the root package `core` package - Generate type definition and javascript files for ESM output - dedicated folder for `esm` and `types` in the `dist` folder to clearly separate concerns - exported in the package.json - Add npm script for `npm pack` configuration - Drop the `postinstall` npm script that built the `core` bundle. It would have been run when the package is installed in dependent projects at dependencies install. And it would have failed as it tries to build the project from TypeScript sources that are not available in the npm package. fix: ConstraintHandler now loads image as everywhere else in the code using `Client.imageBasePath` Using import doesn't work as the image is not available in the npm package. It generated error like this in ViteJS project: Failed to resolve import "../../../images/point.gif" from "../core/dist/esm/view/handler/ConstraintHandler.js". Does the file exist? This gif import had been introduced to make `Anchors.stories.js` retrieve the gif file. Configuring `imageBasePath` as already done in other stories fixes the issue. Don't export EditorCodec and StylesheetCodec as they generate errors. This is a temporary solution to avoid error in dependent project (at least, with ViteJS projects).

Let test the mxgraph core npm package in a TypeScript project. This ensures that the types and the esm code is correctly configured in the package and available for integration.

Drop npm scripts in the root package.json file that only apply to the `core` package

…t variables)

junsikshim · 2022-05-17T01:35:01Z

Great work!
I've never tried Vite yet, does it have some merits?

I agree with the gif import removal. I don't know what I was thinking...

tbouffard · 2022-05-18T08:27:38Z

Great work!

Thanks, I am still working on testing the package with other bundler/build-tools to have a more complete coverage.
We can also merge the PR as it is today and do the fix later if needed.

I've never tried Vite yet, does it have some merits?

About Vite, I choose it here because it allows to check the npm package in 2 ways

unbundled development: direct use of the esm js files, very (very) fast dev server startup and updates
production build with Rollup without any configuration: ensure that the Rollup bundler is able to bundle application with the maxGraph package

It also provides a lot of features not needed here (CSS modules, JSX/TSX, ...) with convenient defaults and a large plugins ecosystem. I like it also for simple project and prototyping because the default configuration lets you start very quickly (a single html page and an JS/TS file)
If you want an overview of such existing tools, you can have a look at https://css-tricks.com/comparing-the-new-generation-of-build-tools/

… types

…tead of relative paths

…ersion settings

tbouffard · 2022-06-09T18:00:12Z

Hi all, today I have been able to test the npm package produced by this Pull Request in an external repository: https://github.com/tbouffard/maxgraph-integration-examples.

I have been able to use the npm package in TypeScript projects built with Parcel, Rollup and ViteJS. I planned to add more integration projects in the future, but IMHO, the 3 existing projects already show that the integration is working.
Notice that I initiated the 3 projects from existing mxGraph examples created to demonstrate the TypeScript integration of mxGraph with typed-mxgraph. It was pretty straightforward. Mainly, remove the mx prefix and change the imports 😸
Even if the existing examples didn't use a lot of the former mxGraph API and custom code, this is a good sign for existing mxGraph users.

During the tests, I have seen some problems with existing function signatures and types, but I won't list them all here. I will create issues or Pull Requests to try to fix them later. There are some comments in the code of my repository.
This repository also describes how I managed to use the locally built maxgraph npm package if someone is interested. Feel free to provide feeback, I am pretty sure there are alternatives or better ways to manage the integration.

I have detected some issues on the generated types, that require the TS projects set "skipLibCheck": true in the TS compilerOptions.
I have attached at the end of this comment the error I get with the ts-example in this repository but I reproduce the problem with my external repository as well. I have been able to quickly fix some errors, but I didn't have time to do more today.
Last but not least, I have updated the GitHub workflow to ensure the ts-example builds without error.

I put this Pull Request in review; I consider this is a good first step to let people built the package locally and test it in their project.
Improvements and fixes could be added later.

Generated types errors

> @maxgraph/ts-example-built-with-vite@0.0.0 build
> tsc && vite build
../core/dist/types/view/cell/CellArray.d.ts:4:5 - error TS2416: Property 'concat' in type 'CellArray' is not assignable to the same property in base type 'Cell[]'.

Type '(items: any) => CellArray' is not assignable to type '{ (...items: ConcatArray[]): Cell[]; (...items: (Cell | ConcatArray)[]): Cell[]; }'.

Call signature return types 'CellArray' and 'Cell[]' are incompatible.

The types returned by 'map(...).pop()' are incompatible between these types.

Type 'Cell | undefined' is not assignable to type 'U | undefined'.

Type 'Cell' is not assignable to type 'U'.

'U' could be instantiated with an arbitrary type which could be unrelated to 'Cell'.
4     concat(items: any): CellArray;

~~~~~~
../core/dist/types/view/cell/CellArray.d.ts:5:5 - error TS2416: Property 'splice' in type 'CellArray' is not assignable to the same property in base type 'Cell[]'.

Type '(arg0: number, ...args: any) => CellArray' is not assignable to type '{ (start: number, deleteCount?: number | undefined): Cell[]; (start: number, deleteCount: number, ...items: Cell[]): Cell[]; }'.

Type 'CellArray' is not assignable to type 'Cell[]'.
5     splice(arg0: number, ...args: any): CellArray;

~~~~~~
../core/dist/types/view/cell/CellArray.d.ts:6:5 - error TS2416: Property 'slice' in type 'CellArray' is not assignable to the same property in base type 'Cell[]'.

Type '(...args: any) => CellArray' is not assignable to type '(start?: number | undefined, end?: number | undefined) => Cell[]'.

Type 'CellArray' is not assignable to type 'Cell[]'.
6     slice(...args: any): CellArray;

~~~~~
../core/dist/types/view/cell/CellArray.d.ts:7:5 - error TS2416: Property 'map' in type 'CellArray' is not assignable to the same property in base type 'Cell[]'.

Type '(arg0: any, ...args: any) => CellArray' is not assignable to type '(callbackfn: (value: Cell, index: number, array: Cell[]) => U, thisArg?: any) => U[]'.

Call signature return types 'CellArray' and 'U[]' are incompatible.

The types returned by 'pop()' are incompatible between these types.

Type 'Cell | undefined' is not assignable to type 'U | undefined'.

Type 'Cell' is not assignable to type 'U'.

'U' could be instantiated with an arbitrary type which could be unrelated to 'Cell'.
7     map(arg0: any, ...args: any): CellArray;

~~~
../core/dist/types/view/cell/CellArray.d.ts:8:5 - error TS2416: Property 'filter' in type 'CellArray' is not assignable to the same property in base type 'Cell[]'.

Type '(arg0: any, ...args: any) => CellArray' is not assignable to type '{ (predicate: (value: Cell, index: number, array: Cell[]) => value is S, thisArg?: any): S[]; (predicate: (value: Cell, index: number, array: Cell[]) => unknown, thisArg?: any): Cell[]; }'.

Call signature return types 'CellArray' and 'any[]' are incompatible.

The types returned by 'map(...).pop()' are incompatible between these types.

Type 'Cell | undefined' is not assignable to type 'U | undefined'.

Type 'Cell' is not assignable to type 'U'.

'U' could be instantiated with an arbitrary type which could be unrelated to 'Cell'.

8     filter(arg0: any, ...args: any): CellArray;

~~~~~~
../core/dist/types/view/layout/HierarchicalLayout.d.ts:203:5 - error TS2416: Property 'traverse' in type 'HierarchicalLayout' is not assignable to the same property in base type 'GraphLayout'.

Type '(vertex: Cell, directed: boolean | undefined, edge: Cell | null | undefined, allVertices: { [key: string]: Cell; } | null | undefined, currentComp: { [key: string]: Cell | null; }, hierarchyVertices: GraphHierarchyNode[], filledVertexSet?: { ...; } | ... 1 more ... | undefined) => { ...; }' is not assignable to type '(vertex: Cell, directed?: boolean | undefined, func?: Function | undefined, edge?: Cell | undefined, visited?: Dictionary<Cell, boolean> | undefined) => void'.
203     traverse(vertex: Cell, directed: boolean | undefined, edge: Cell | null | undefined, allVertices: {

~~~~~~~~
../core/dist/types/view/layout/SwimlaneLayout.d.ts:220:5 - error TS2416: Property 'traverse' in type 'SwimlaneLayout' is not assignable to the same property in base type 'GraphLayout'.

Type '(vertex: Cell | null | undefined, directed: boolean, edge: Cell | null, allVertices: { [key: string]: Cell; } | null | undefined, currentComp: { [key: string]: Cell; }, hierarchyVertices: GraphHierarchyNode[], filledVertexSet: { ...; } | ... 1 more ... | undefined, swimlaneIndex: number) => { ...; }' is not assignable to type '(vertex: Cell, directed?: boolean | undefined, func?: Function | undefined, edge?: Cell | undefined, visited?: Dictionary<Cell, boolean> | undefined) => void'.
220     traverse(vertex: Cell | null | undefined, directed: boolean, edge: Cell | null, allVertices: {

tbouffard · 2022-06-09T18:15:58Z

cc @lalicw, @Seebiscuit, @wrw1997, @cd-yang for testing as you noticed interest for a relase or the npm package

- custom shapes - activate rubberband - panning and overflow hidden - bump vite to 2.9.12

tbouffard · 2022-06-13T04:13:02Z

packages/core/src/Client.ts

+   * Contains the current version of the maxGraph library.
   */
-  static VERSION = '4.2.2';
+  static VERSION = '0.1.0';


ℹ️ in the future, we will automate the value update during release

not intended to be published

tbouffard · 2022-07-05T06:07:54Z

I am going to merge this Pull Request to let people build the npm package locally and test it in their projects.

tbouffard added 2 commits May 9, 2022 17:56

feat: create a TypeScript integration example built with ViteJS

2b3e691

Let test the mxgraph core npm package in a TypeScript project. This ensures that the types and the esm code is correctly configured in the package and available for integration.

tbouffard mentioned this pull request May 9, 2022

How to integrate maxGraph into my own project #84

Closed

GH workflow: run npm script from the packages/core directory

e5b3756

Drop npm scripts in the root package.json file that only apply to the `core` package

tbouffard force-pushed the chore/prepare_npm_package branch from 48c5258 to e5b3756 Compare May 9, 2022 16:19

Make build work on Windows (introduce 'cross-env' to set environmen…

428d004

…t variables)

tbouffard changed the title ~~chore: improve the configuration to be able to build the npm package~~ chore: improve the configuration to build the npm package May 10, 2022

This was referenced Jun 4, 2022

Move back to the Apache-2.0 license #89

Closed

Versioning strategy #92

Closed

tbouffard added 7 commits June 9, 2022 13:49

Merge branch 'development' into chore/prepare_npm_package

9f32c76

update vite dependency

8dacd28

ts-example: set skipLibCheck=true until we fix the generated maxgraph…

71e59d6

… types

fix generated definition files: some imports were using src/types ins…

1961781

…tead of relative paths

gh workflow: introduce .nvmrc to share both development and CI node v…

6e0b46d

…ersion settings

ts-example: update package.json

d40dc9a

build workflow: also build the example

d7500da

tbouffard marked this pull request as ready for review June 9, 2022 18:10

tbouffard requested review from junsikshim and mcyph June 9, 2022 18:10

tbouffard added 3 commits June 10, 2022 08:02

update comments about "skipLibCheck"

e85deeb

improve the ts-example

8119b76

- custom shapes - activate rubberband - panning and overflow hidden - bump vite to 2.9.12

Update Client.VERSION: use the same value as the package.json version

cae2172

tbouffard commented Jun 13, 2022

View reviewed changes

tbouffard mentioned this pull request Jun 30, 2022

Failed to resolve entry for package "@maxgraph/core" maxGraph/maxgraph-integration-examples#12

Closed

tbouffard added 2 commits July 5, 2022 06:17

Merge branch 'development' into chore/prepare_npm_package

12a797a

bump checkout and setup-node actions

beb0211

tbouffard added 4 commits July 5, 2022 06:42

do not set version in the 'html' package

222d032

not intended to be published

README: explain how to build npm package locally

2d05ca7

README: improve usage

6fff050

vitejs example: improve how-to build paragraph in the README

7a9eef2

tbouffard mentioned this pull request Jul 5, 2022

Some generated types are invalid: CellArray and Layouts #96

Closed

2 tasks

tbouffard added 3 commits July 5, 2022 07:43

vitejs example: improve how-to build paragraph in the README

a5c924b

ts-example: add link to skipLibCheck issue

e14a826

ts-example: add link to skipLibCheck issue

94daa6f

tbouffard mentioned this pull request Jul 5, 2022

Restore EditorCodec and StylesheetCodec exports #97

Closed

tbouffard merged commit 893ad44 into development Jul 5, 2022

tbouffard deleted the chore/prepare_npm_package branch July 5, 2022 06:08

tbouffard mentioned this pull request Sep 23, 2022

SvgCanvas2D - unexpected behavior of roundrect #107

Closed

tbouffard added the chore Build, CI/CD or repository tasks (issues/PR maintenance, environments, ...) label Nov 20, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

chore: improve the configuration to build the npm package #87

chore: improve the configuration to build the npm package #87

Uh oh!

tbouffard commented May 9, 2022 •

edited

Loading

Uh oh!

junsikshim commented May 17, 2022

Uh oh!

tbouffard commented May 18, 2022 •

edited

Loading

Uh oh!

tbouffard commented Jun 9, 2022 •

edited

Loading

Uh oh!

tbouffard commented Jun 9, 2022

Uh oh!

tbouffard Jun 13, 2022

Uh oh!

tbouffard commented Jul 5, 2022 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

chore: improve the configuration to build the npm package #87

chore: improve the configuration to build the npm package #87

Uh oh!

Conversation

tbouffard commented May 9, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Notes

How to use

Testing project

About the gif import removal

Commented exports

Uh oh!

junsikshim commented May 17, 2022

Uh oh!

tbouffard commented May 18, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tbouffard commented Jun 9, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tbouffard commented Jun 9, 2022

Uh oh!

tbouffard Jun 13, 2022

Choose a reason for hiding this comment

Uh oh!

tbouffard commented Jul 5, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

tbouffard commented May 9, 2022 •

edited

Loading

tbouffard commented May 18, 2022 •

edited

Loading

tbouffard commented Jun 9, 2022 •

edited

Loading

tbouffard commented Jul 5, 2022 •

edited

Loading