Add documentation about npm unlink in DG

[yucheng11122017]

Please confirm that you have searched existing issues in the repo

Yes, I have searched the existing issues

Any related issues?

No response

What is the area that this feature belongs to?

Documentation

Is your feature request related to a problem? Please describe.

When developing, we have to use npm link in the cli package. See instructions in DG. However, when trying to test using the released version of markbind, it is necessary to unlink (npm unlink markbind-cli)from the cli package. This step is not documented in the DG.

Describe the solution you'd like

Add instructions on unlinking from cli package when trying to use the released version of markbind.

Describe alternatives you've considered

No response

Additional context

No response

[tlylt]

Isn't the following section in the FAQ sufficient? Uninstalling will work:

How do I move back to the released version of MarkBind?

To go back to the released version of MarkBind, run npm un -g markbind-cli, followed by npm i -g markbind-cli.

[yucheng11122017]

Isn't the following section in the FAQ sufficient? Uninstalling will work:

How do I move back to the released version of MarkBind?

To go back to the released version of MarkBind, run npm un -g markbind-cli, followed by npm i -g markbind-cli.

It didn't seem to work with @LamJiuFong when we were trouble shooting for him that day. Only after he ran npm unlink did it unlink properly

[LamJiuFong]

Yup, it only worked after I ran npm unlink markbind-cli

However, according to https://docs.npmjs.com/cli/v8/commands/npm-uninstall#examples, unlink is just an alias for uninstall, so not sure what was the issue when running npm un -g markbind-cli

Edit: I am thinking of this potential reason: npm unlink uninstalls the local package and npm un -g uninstalls the global package but not the local package When we run a module, it will first search from the local packages (node_modules). If there exist a local package, it will use it instead of using the global package. That's why running npm un -g markbind-cli and npm i -g markbind-cli wouldn't work since the local package is not affected and still links to the local markbind-cli

[tlylt]

Yup, it only worked after I ran npm unlink markbind-cli

What worked after you ran unlink?

[yucheng11122017]

Yup, it only worked after I ran npm unlink markbind-cli

What worked after you ran unlink?

The delinking - only after running npm unlink, he could use the released version of markbind

[tlylt]

Yup, it only worked after I ran npm unlink markbind-cli

What worked after you ran unlink?

The delinking - only after running npm unlink, he could use the released version of markbind

Perhaps a detailed description of the steps taken (what commands ran and what results etc) would help debug the root cause.

[LamJiuFong]

First, I run markbind init in an empty folder, there's an error (some issues in my package/cli folder), Then in the empty folder, I run npm un -g markbind-cli -> npm i -g markbind-cli -> markbind init, the error appears again Then in the empty folder, I run npm unlink markbind-cli -> npm un -g markbind-cli -> npm i -g markbind-cli -> markbind init, initialisation run successfully

[tlylt]

First, I run markbind init in an empty folder, there's an error (some issues in my package/cli folder),

Then in the empty folder, I run npm un -g markbind-cli -> npm i -g markbind-cli -> markbind init, the error appears again

Then in the empty folder, I run npm unlink markbind-cli -> npm un -g markbind-cli -> npm i -g markbind-cli -> markbind init, initialisation run successfully

Some error -> what error exactly? Any logs?

[LamJiuFong]

Sorry, I forgot what was the exact error, I remember it was related to missing layouts The logs was something along the line Could not find ../Layouts

[yucheng11122017]

Sorry, I forgot what was the exact error, I remember it was related to missing layouts The logs was something along the line Could not find ../Layouts

Yes this error came about because of some pull issue where the Layout.ts didnt get pull into the local repo. So because it wasn't unlinked properly, it resulted in this error.

[tlylt]

Sorry, I forgot what was the exact error, I remember it was related to missing layouts

The logs was something along the line Could not find ../Layouts

Hmm sorry so this error is not reproducible? If not could you reproduce and capture the error log when convenient?

[yucheng11122017]

Hmmm I just tried it and the commands in the DG npm un -g markbind-cli and then npm i -g markbind-cli seems to work for me on Windows. @LamJiuFong could you try again on your computer (Mac) and see if this is replicable? If not I will close this issue.

[Tim-Siu]

Running the sequence of operation suggested by @LamJiuFong , it seems like the current set of commands in DG suffice and results in no error. (macOS environment)

[LamJiuFong]

I gave @Tim-Siu this set of instructions to try replicating the bug on his Mac:

1. remove Layout.ts in core/src/Layout
2. npm run setup
3. npm link in packages/cli

then in an empty folder:
3. npm link markbind-cli
4. marbind init (should have an error)
5. npm un -g markbind-cli
6. npm i -g markbind-cli
7. markbind init (observe if there is still any error)

Our results in Step 7 is different, @Tim-Siu's one has no error but mine still has the same error in Step 4. However, I tried another approach (adding another command npm unlink markbind-cli right before Step 5) and it doesn't work too. I think it might be my own laptop's problem

[tlylt]

3. npm link markbind-cli

Why do you need to do this again in an empty folder ? Once you npm link and the package is available globally, the markbind init call will invoke the master branch markbind.

To get to the released version of MarkBind

• npm un -g markbind-cli then npm i -g markbind-cli

To get to the master branch version of MarkBind

• navigating to the cloned packages/cli folder and running npm link

[LamJiuFong]

Why do you need to do this again in an empty folder ? Once you npm link and the package is available globally, the markbind init call will invoke the master branch markbind.

Sorry, I was following the instructions here: https://docs.npmjs.com/cli/v8/commands/npm-link I understand that it might be doing extra work but I am not sure how would this affect anything

[tlylt]

Sorry, I was following the instructions here: https://docs.npmjs.com/cli/v8/commands/npm-link

I see. The steps in the docs should be relevant in the case that you are working on another node/npm project that relies/imports on your npm package. In our case we are making a cli tool available globally, it's not necessary for you to make in available in the folder that you want to invoke it in order to call the markbind cli (iirc).

I understand that it might be doing extra work but I am not sure how would this affect anything

I wonder if your empty folder is not an empty one but one with a node_modules as mentioned in the docs, will the error still occur? You can populate it by running npm init -y

Also btw...you still have not posted the exact error message🙃

[LamJiuFong]

Hi @tlylt , so sorry for the late reply.

I see. The steps in the docs should be relevant in the case that you are working on another node/npm project that relies/imports on your npm package. In our case we are making a cli tool available globally, it's not necessary for you to make in available in the folder that you want to invoke it in order to call the markbind cli (iirc).

Ohh I see, I agree with you that it is unnecessary to do npm link markbind-cli again in our case.

Also btw...you still have not posted the exact error message🙃

These are the exact error messages

1. After deleting Layout.ts and run npm run setup, this error occured:

   

2. Running markbind init in an empty folder

   

3. Run npm un -g markbind-cli and npm i -g markbind-cli

   

4. Running markbind init again

   

I wonder if your empty folder is not an empty one but one with a node_modules as mentioned in the docs, will the error still occur? You can populate it by running npm init -y

I tried this method in another folder after running npm init -y, and followed the workflow above. The same errors occured though (I followed the same steps 1-4)

However, after adding the Layout.ts back and running npm run setup, I ran markbind init in both folders, and there is no error:

I am thinking if my laptop still links markbind-cli to my local version instead of the released version even after I reinstall it globally

[tlylt]

I am thinking if my laptop still links markbind-cli to my local version instead of the released version even after I reinstall it globally

From the logs it looks like you are. You can confirm it either by checking the npm global installation folder in your machine or make some obvious change in the markbind repo instead of removing the Layout.ts to test it (e.g. add a console log somewhere or edit the output of markbind init).

Maybe try testing after you run npm un -g markbind-cli, are you able to run markbind --version or markbind init before you even re-install it globally.

[LamJiuFong]

I added a console.log in init.js

Ran npm run setup and npm link

In the empty folder (without running npm init -y), I did the following: 1) npm ls -g

2) markbind init the "hi" is printed

3) npm un -g markbind-cli followed with npm ls -g, the global package is uninstalled <img width="433" alt="Screenshot 2024-03-28 at 2 26 21 AM" src="https://github.com/MarkBind/markbind/assets/122192553/917c37a8-c73a-4a3f-ba84-c9a4d339b6be">

4) But markbind --version and markbind init works

5) Ran npm i -g markbind-cli

6) Ran npm ls --g and markbind init

I followed the steps above in another folder (with npm init -y) and the results were the same.

[tlylt]

But markbind --version and markbind init works

@LamJiuFong Since that's the case, could you try adding a print statement to console log the location of markbind-cli files? i.e. find out where it is executing from

Could you also try double-checking the folder and verify that the markbind-cli folder is indeed deleted?

On macOS, global packages installed with npm are typically stored in the /usr/local/lib/node_modules directory. However, the exact location can depend on how Node.js and npm were installed on your system.

If you've installed Node.js using a version manager like nvm, the global packages might be stored in a directory related to nvm, usually under your home directory, like ~/.nvm/versions/node//lib/node_modules.

[tlylt]

@LamJiuFong any updates? If not we can close this issue.