Deprecate mermaid.cli or @mermaid-js/mermaid-cli?

[sidharthv96]

Maybe the website is using https://www.npmjs.com/package/mermaid.cli instead of https://www.npmjs.com/package/@mermaid-js/mermaid-cli?

If anyone has access to that NPM package, maybe they can do an npm deprecate on it, something like:

npm deprecate mermaid.cli "Development has moved to the '@mermaid-js/mermaid-cli' package"

Ideally we'd also close all the open issues/PRs in https://github.com/mermaidjs/mermaid.cli and archive that repo since it looks like there are still people reporting bugs there.

Maybe with a message that says:

Development on this project has moved to https://github.com/mermaid-js/mermaid-cli

If this issue/PR is still valid, please re-create this issue in the new repository and add a link to this issue/PR.

A script like https://gist.github.com/mauritsvanrees/f0dc7d829a1957a1771adbf0e86057c5 might help, but then again, there are only ~60 or so open issues/PRs, so it might be faster to manually close every issue.

Originally posted by @aloisklink in #432 (comment)

---

Yes, We should archive the GitHub repo, but the mermaid.cli package name seems too good to throw away.

npm i mermaid.cli
npm i @mermaid-js/mermaid-cli
npm i mmdc # or `npx mmdc` to install and run in one command

IMHO, The first one looks better, and is in line with mermaid.live

Wonder what's keeping us from going back to that package with a new major release?

Edit by @aloisklink, added npm i mmdc possibility since it's available, see #433 (comment)

[alixander]

yeah i was using 9.1.7, installed with brew. It looks like brew dist is discontinued now?

here's the cmd i ran to render: https://github.com/terrastruct/text-to-diagram-site/blob/master/ci/render.sh#L25

noted about documenting the versions, i'll be sure to include that.

ooc, i don't see any changes in the 9.2.2 release notes that affect rendering. is the release notes only a subset of changes?

[alixander]

i've made the changes! can you or a Mermaid contributor take a look? terrastruct/text-to-diagram-site#25

[alixander]

notably, in the chess example (https://github.com/terrastruct/text-to-diagram-site/pull/25/files?short_path=d103659#diff-41b7f97d22bf5bc6d77b286fcbcff8ca4c73ac57573c956cafc248eee97c9fec), one of the labels is randomly placed.

if you'd like, i can file an issue on the Mermaid repo

[sidharthv96]

That was crazy fast!

Yes, brew is discontinued because of the chromium dependency. #288 (comment)

We'll update the docs to make this clearer.

[alixander]

gotcha. it's likely you guys have looked into it already, but if not, Playwright can install dependencies upon first run on user machines, so you don't have to bundle them with the package. no mo chromium dependency

it's also super simple to use: e.g. terrastruct/d2#111

[sidharthv96]

I've been a very happy user and occasional contributor to Playwright for a while.
@MindaugasLaganeckas @aloisklink do you think it's worth switching?

Based on Homebrew/homebrew-core#98549, not sure if PW will help with brew.

[aloisklink]

Wonder what's keeping us from going back to that package [npm install mermaid.cli] with a new major release?

I think it's mainly for permissions. Most projects are instead moving to @org/package because that way it's much easier to manage project permissions, see https://docs.npmjs.com/organizations

It looks like the owner of mermaid.cli is @tylerlong

user@computer:~$ npm owner ls mermaid.cli
tylerlong <tyler4long@gmail.com>

It's probably easier to just ask them to run npm deprecate mermaid.cli "Development has moved to the '@mermaid-js/mermaid-cli' package" then to ask them to mess with NPM permissions :)

I'm not even sure if it's possible to move ownership of a normal NPM package to an NPM @mermaid-js organization account.

---

ooc, i don't see any changes in the 9.2.2 release notes that affect rendering. is the release notes only a subset of changes?

It's part of updating the Mermaid back-end, but it's a bit hidden, see below:

🧰 Maintenance

• chore(deps-dev): bump mermaid from 9.1.7 to 9.2.2 @aloisklink (#423)

From https://github.com/mermaid-js/mermaid-cli/releases/tag/9.2.2

Maybe we should make that more prominent? Recommendations are welcome :)
We could make the first line of the release notes something like This version of mermaid-cli is bundled with v9.x.x of mermaid, see [Mermaid v9.x.x release notes][link].

We could also add it to the mmdc --version, so maybe it logs something like: 9.2.2+mermaid-version.9.2.2. Normally, we try to keep the mermaid-cli version identical to the bundled mermaid version, but very occasionally, they do drift slightly.

---

Playwright can install dependencies upon first run on user machines, so you don't have to bundle them with the package. no more chromium dependency

I prefer how puppeteer does it. It installs chromium automatically when running npm install, so that way you can use mermaid-cli offline after the first install.

There's also some docs on how to use a pre-downloaded chromium version for puppeteer (e.g. #331), which is used by the Mermaid docker image and people that have strict corporate security rules. If we switch to using playwright, all of those instructions will also need to be updated (maybe even make it impossible since I believe playwright uses forked versions of browsers).

do you think it's worth switching?

I think the developer experience with playwright is much nicer (especially when writing tests), but the mermaid-cli use case is really basic, so I don't see much reason to switch :)

Ideally, the main mermaid project will add server-side rendering, so that we can completely remove chromium (see mermaid-js/mermaid#3650), but who knows if that is even possible!

[sidharthv96]

I'm not even sure if it's possible to move ownership of a normal NPM package to an NPM @mermaid-js organization account.

I think this should allow access to publish.

npm access grant read-write mermaid-js:developers mermaid.cli

Then, if we add an mmdc alias to the package, people would be able to run both npx mermaid.cli ... and mmdc ... if they install globally.

[sidharthv96]

@MindaugasLaganeckas @aloisklink we've got access to the mermaid.cli npm package now.

I just tried publishing an RC https://www.npmjs.com/package/mermaid.cli/v/9.2.2-rc.1

npx mermaid.cli@9.2.2-rc.1 --help

works.

[aloisklink]

@MindaugasLaganeckas @aloisklink we've got access to the mermaid.cli npm package now.

🚀 Awesome!

By the way, I've also reserved https://www.npmjs.com/package/mmdc in case you guys want to use it (and to prevent a typo-squatting attack).

I've also just noticed that npx @mermaid-js/mermaid-cli --help works too!

I'm slightly leaning towards keeping @mermaid-js/mermaid-cli, so that everybody doesn't need to update their code (especially we already asked them 3 years ago to move from mermaid.cli to @mermaid-js/mermaid-cli).

But it could be worth asking what @knsv thinks, especially since archiving the old https://github.com/mermaidjs/mermaid.cli will need admin permissions!

[MindaugasLaganeckas]

I also agree that @knsv should decide the way forward. 😄
Thank you for looking into it!!

[aloisklink]

@knsv has placed a deprecation warning on the mermaid.cli package:

Additionally, I've managed to gain Admin permissions for the old https://github.com/mermaidjs/mermaid.cli repo, and I spent a few hours going through and closing every remaining open issue and PR, telling everybody that https://github.com/mermaid-js/mermaid-cli is the currently maintained fork of mermaid-cli!

https://github.com/mermaidjs/mermaid.cli has now been archived 🥳!

We might also want to archive the entire @mermaidjs organization too, since GitHub has recently added that feature, see https://docs.github.com/en/organizations/managing-organization-settings/archiving-an-organization