How can I create a gleam package that wraps an npm package?

[chuckwondo]

I want to create a gleam package that wraps a javascript package, but I can't seem to find a repository that does this, so I'm not sure what a reasonable approach might be. If anybody can point me to an existing repo that does so, that would be great. If not, how might I go about doing so?

In particular, I'm initially interested in a reasonable repo structure, along with a build/test workflow. I'm not initially concerned with the actual publication end of the details, other than parts of the repo structure that would have an impact on that.

As a potentially simple example, let's say I want to create an XML-to-JSON converter in gleam, but rather than writing it from scratch in gleam, I want to wrap the existing xml2json npm package and simply write a gleam api with external types and functions that reference the xml2json npm package.

What's not clear to me is how to reference the npm package as a dependency since I don't believe that gleam itself can handle such dependencies. As far as I'm aware, gleam only deals with hex packages, right?

I suspect that along with my gleam.toml file, I'd need a package.json file. If that's the case, then how might I reasonably coordinate the use of both gleam and npm (or yarn)? Would it make sense to add "scripts" to my package.json file and have scripts that call out to gleam as part of various build and test commands?

In addition, the rad companion to the gleam build runner appears to do something along the lines of what I'm looking for in terms of leveraging npm packages (under the priv folder), but the ffi mjs files include some relative import paths that seem odd to me, and it's not clear how they were derived. For example, these lines: https://github.com/tynanbe/rad/blob/main/src/rad_ffi.mjs#L4-L8

It appears that the rad package simply bundles the necessary npm packages in the repo, but that's not the approach I would want to take. I'd rather perhaps list dependencies in package.json and have my build process pull them, although I realize that what would ultimately be published as a gleam package (e.g., an "xml2json" gleam package) would perhaps require the xml2json npm package (along with its transient deps) to be bundled within the published gleam package.

Are there any existing conventions or recommendations for creating a gleam package that wraps an npm package?

[lpil]

Aye, Gleam uses Hex. If you have additional dependencies such as OS packages or npm packages you'll need to document the additional steps required by the programmer to install them.

[chuckwondo]

Right, I'm looking for some guidance on how I might structure things, such as:

1. How to create a gleam package that is essentially an ffi/wrapper for some npm package. I'm not familiar with hex, so I don't know what specifically would need to be published in such a gleam package.
2. How I might structure a gleam project that uses such a gleam "wrapper" package. I suspect such a project would need both a gleam.toml file (to reference the gleam ffi/wrapper dep) as well as a package.json file (to reference the npm dep that is "wrapped" by the gleam dep)

Given that gleam uses hex, it seems to me that gleam is much easier to integrate with erlang projects than with javascript projects, so I'm looking for guidance on how I might introduce gleam into existing js/ts projects, where I'll need to use both hex and npm, an particularly looking for a reasonable way to write gleam "wrappers" for existing npm package to avoid having to write gleam ports for every npm package I currently use, when there is currently no gleam equivalent.

[lpil]

I don't believe you would need any additions to the project beyond documenting that the user needs to run npm install xyz or such. Node doesn't require a package.json file to use node modules.