Add CMake + Vcpkg example

[Pospelove]

WIP, will extend docs and add node-addon-api example

[gabrielschulhof]

@Pospelove thanks for the examples! Is there a reason build_with_cmake is being replaced with build_with_cmakejs rather than being shown as an example in addition to build_with_cmake?

[Pospelove]

Hello everyone, and thanks for the interest! I’m planning to finish this PR by adding a C++ example and running the necessary tests.

There are a few points I’d like to discuss further, as they might need some consensus:

1. vcpkg submodule: In the draft, I’ve included a vcpkg submodule, which is the recommended approach for manifest mode. Do you think we should stick with this? Or would it be better to simply mention it as an option, provide a link to the relevant documentation, and let users rely on their system-installed vcpkg instead?

2. CMake/CMake.js naming: @gabrielschulhof raised a good point about the naming inconsistency between cmake and cmakejs. I’d love to hear your thoughts on how we can make this clearer.

I updated the CMake.js section of the docs because the mismatch between CMake and CMake.js can be confusing for developers who are coming from a C++ background.

To provide some context, the node-api-headers and node-addon-api vcpkg ports are quite handy for building native addons without needing CMake.js or npm at all. Here’s why they might be a good fit for many projects:

1. They’re ideal for existing C++ projects that are already managed with CMake and vcpkg, where CMake.js isn’t typically used.
2. They make it straightforward to connect Node.js to your C++ code—similar to integrating Lua or Boost.Python. But! Unlike the C++ Embedder API, this method still creates a native addon.

[Pospelove]

P.S. I'll be able to get back to this PR once examples land

P.S.S. I use the node-addon-api in https://github.com/skyrim-multiplayer/skymp for a long time and it works so much better than anything else like node-gyp or cmake.js. The mix of C++ and TypeScript code is being built by CMake build system. In the past the project was invoking cmake.js via npm as a subprocess from root CMake build system. Imagine what a rabbithole there was!

[BurningEnlightenment]

vcpkg submodule: In the draft, I’ve included a vcpkg submodule, which is the recommended approach for manifest mode. Do you think we should stick with this? Or would it be better to simply mention it as an option, provide a link to the relevant documentation, and let users rely on their system-installed vcpkg instead?

git submodules cannot work if the package is published and used as a dependency.

[Pospelove]

vcpkg submodule: In the draft, I’ve included a vcpkg submodule, which is the recommended approach for manifest mode. Do you think we should stick with this? Or would it be better to simply mention it as an option, provide a link to the relevant documentation, and let users rely on their system-installed vcpkg instead?

git submodules cannot work if the package is published and used as a dependency.

Good point. CMake-based filesystem isn't good in terms of publishing npm packages anyways. This will be another topic: how do one publish a vcpkg+cmake backed Node addon. For now, I didn't publish any and there are no established best practices.

vcpkg submodule is logically a dev-dependency, it's not needed once your Node addon built since it's only ensures dependencies compiled.

[mhdawson]

@Pospelove the node-api team is just waiting for this to be rebased/non-draft before taking a closer look.

[KevinEady]

Hi @Pospelove,

Do you still plan on working on this pull request? It will need to be rebased and not in draft status.

[Pospelove]

Hi @KevinEady,
I merged main branch into my feature branch. Hope the PR can me squash-committed.

@vmoroz Could you please take a look?