capacitor: explain that we have to add plugin as devDependencies

[rbalet]

Description

I had quite a trouble making everything run while migrating from a non nx repo to a mono repo with angular-ionic and capacitor. I'm finally through, but do think that a nice documentation would help a lot of people.

Here are some suggestion just fresh out of my experience (I'd be glad to do a pull-request if this issue is accepted).

Let's take https://nxext.dev/docs/ionic-angular/generators.html as example

1. Explain that we first need to generate an angular application with nx g @nx/angular:app apps/appName (maybe link it to this page
2. After Options add some new cli created by the project, like nx run up4it-app:copy:ios, nx run up4it-app:add:ios, ... (if found it actually over on the former docs - nxtend -> I would create something similar as this was really helpful to me
3. If possible, it would be nice to put a nice orang label on the nxtend website, and put a deprecated, as this is actually pretty hard to see the difference with the actual nxext (maybe it's just me '^^)
4. Inform that every plugin have to be added inside the package.json devDependencies, as "@capacitor-community/file-opener": "../../node_modules/@capacitor-community/file-opener",, if you don't then it wont take over those plugins while compiling to the different platform (This one was hard to find, as it isn't explained anywhere to what I see).

Voilà, with that we would have a strong basis to understand how to start :) Cheers

[edbzn]

Hey @rbalet, thanks for the suggestions, go ahead and raise a PR, I will have a look at it. Thank you!

[rbalet]

Hi @edbzn , I've tried to do the PR, but got some unknown problems,

I've tried then multiple pull request, can you point me out the error ? https://github.com/nxext/nx-extensions/actions/runs/11234981741/job/31231952925?pr=1125

Pull requests

1. Executors: https://github.com/nxext/nx-extensions/pull/1125
2. Installation: https://github.com/nxext/nx-extensions/pull/1126
3. Configs: https://github.com/nxext/nx-extensions/pull/1127

[edbzn]

@rbalet There's a formatting issue, you have to run pnpm format and commit the result. Could you also group everything in one single PR and name the commits with docs instead of feat, please?

[rbalet]

@edbzn Yes I can, I'll remove the pullrequest when done.

I did the pnpm format but it somehow removes the executors back to an empty file. do you have an Idea on the reason why ?

And could you please unarchive the nxtend library for today? I've already prepared the pull request to add the deprecated banner like this

https://github.com/nxtend-team/nxtend/compare/main...rbalet:nxtend:patch-1

[rbalet]

@edbzn Here, the output of the pnpm format

It doesn't make that much sens to me

[edbzn]

Yeah, these docs are generated automatically, @DominikPieper better knows what to do.

Edit: @rbalet I think you just need to rename the file, it happens because ionic-angular has no executors. However I think repeating the capacitor docs here is just duplication, what about adding a link to the capacitor plugin in the getting started document you created, explaining that the configuration generator generates capacitor targets in the project configuration?

[edbzn]

I contacted the owner of the Nxtend repository so we can merge your PR and hopefully deploy the banner.

[DominikPieper]

@rbalet Yes the docs are autogenerated with static filenames. If you use that name the generation will just run through and override it ^^'

[rbalet]

@DominikPieper Could you have a look at this pull-request ? https://github.com/nxext/nx-extensions/pull/1125/files

This is what I would have seen in the executors file, it does copy the executors logic of the former doc and I do find it to be quite helpful, and I don't know how to generate it then

But maybe I could just push the both of them in one branch. Installation: https://github.com/nxext/nx-extensions/pull/1126 Configs: https://github.com/nxext/nx-extensions/pull/1127

this would already be a nice addition, as the installation was for me the most important one, rest can be guessed

[DominikPieper]

@rbalet Installation should work fine, just the "executor" and "generator" files re generated each time automatically (https://github.com/nxext/nx-extensions/blob/5d9c0f0ef3dfa1b2d1dd06a3bf08ba08e38224c8/tools/scripts/documentation/documentation.ts)

They are more like jsdoc and read each plugins executors.json and generators.json. If you add the executors file under an other name it should work fine.

Cause theres a empty executors fine it will still iterate over the non existing executors and create the new file

[edbzn]

I'd suggest not duplicating executors docs of capacitor, it will become outdated if we change something, I'd recommend adding a note about capacitor in the getting started document of ionic-angular and links to the doc of capacitor.

[DominikPieper]

@edbzn is the executors.json file still needed with crystal? @rbalet maybe we should just link the capacitor doc instead of copying it 🤔

[edbzn]

Yes and no. :smile:

If we want to be backward compatible we will need to keep public executors to not break existing apps. But we can also delete them and only export a plugin that configures project targets and executes capacitor.

I'd suggest adding a plugin that calls directly capacitor without using the existing executors and keeping the executors for now.

[rbalet]

Ok, @edbzn @DominikPieper , Here's a proposal :) I've taken in account your notes, and added a line that links to the capacitor documentation.

I think it's good enough for the moment. Hope you'll agree ;)