feat: export cli internals for programmatic usage

[matthewvolk]

This PR adds two more entry points to the @opennextjs/cloudflare package:

1. "./cli/*"
2. "./lib/*"

"./cli/*" is intended to be an entry point used by developers who are looking to use the opennextjs-cloudflare CLI programmatically, which is a use case especially relevant for using @opennextjs/cloudflare with Workers for Platforms.

"./lib/*" is an entry point that intentionally duplicates the existing catch-all ("./*") entry point; undocumented for now, but in the future can be used to more explicitly differentiate between exports intended for the Next.js app being deployed to Cloudflare, vs. exports related to programmatic usage of the CLI.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3b7b35b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@opennextjs/cloudflare	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[james-elicx]

How come you need to call the command programmatically via importing instead of using something like exec? Is there a benefit that is gained with that?

I'm thinking from the POV of those imports are not going to be considered stable and would be subject to breaking changes without notice, whereas running the CLI commands with the CLI will not be subject to breaking changes unless we release a major version.

[matthewvolk]

@james-elicx Fair point!

For context, I was fighting some of the commands that expect certain configuration files to be present inside the user's Next.js project (example). We were hoping to obfuscate those configuration files behind a CLI we're building on top of opennextjs-cloudflare to minimize the amount of configuration that our customers need to learn in order to deploy their catalyst applications to CF.

This PR allowed us to skip the compileConfig step by directly importing from packages/cloudflare/src/cli/build/build.ts, but we later found out that other parts of the build/preview command internals also rely on the filesystem.

It would be awesome if these types of build configs could be passed as objects to the underlying Node API's as an alternative to configuration files present in the project files. I'm still getting familiar with this repository so maybe that's more complicated than I'm anticipating.

To your point, I think we can go ahead and close this PR, but we're super interested in finding out if there's an appetite for passing configurations as objects. We'd be open to helping out with that, if the team is open to the overall direction!

[james-elicx]

For context, I was fighting some of the commands that expect certain configuration files to be present inside the user's Next.js project (example). We were hoping to obfuscate those configuration files behind a CLI we're building on top of opennextjs-cloudflare to minimize the amount of configuration that our customers need to learn in order to deploy their catalyst applications to CF.

This PR allowed us to skip the compileConfig step by directly importing from packages/cloudflare/src/cli/build/build.ts, but we later found out that other parts of the build/preview command internals also rely on the filesystem.

It would be awesome if these types of build configs could be passed as objects to the underlying Node API's as an alternative to configuration files present in the project files. I'm still getting familiar with this repository so maybe that's more complicated than I'm anticipating.

Would it help if you were able to pass a custom path for the open next config instead, and you could then reference one in your own build dir? We support that with the Wrangler config, so I don't see why we shouldn't with the OpenNext config.

[dario-piotrowicz]

Sorry for the late review 🙇

Looks good to me, although as I commented maybe we should stick with /api for now 🤔

Also the Cloudflare open-next docs should be updated to use these new endpoint, would you have some extra cycles to do it? or if not I can give it a go please let me know 🙂

(Oh I see you thought of keeping this undocumented for now? 🤔, ok that could be ok too I guess 🤔)

[dario-piotrowicz]

I know I suggested lib but by looking at the PR it looks to me like we might as well stick with api since that's already used 🙂

[dario-piotrowicz]

Oh, I just noticed the previous conversation in the PR 😓

I agree with @james-elicx that exporting cli/* could introduce non-versioned breaking changes, I think that the solution for that would be to have an index file that exports the cli utilities, that would create an appropriate interface that would be properly versioned (and open-next would be able to decide what utilities expose etc...)

I feel like this is however not fully in line with the team's preference? I'd be keen to hear what @james-elicx , @conico974 and @vicb think.

[conico974]

We cannot make this work unfortunately, the open-next.config.ts is compiled at build time to both the edge and node runtime.
It is also mandatory to have the compiled version at runtime.
The solution from james is the correct one, just a config path that you could set to whatever you need

[vicb]

@matthewvolk what's the status on your side here?

I read the comments and agree that exporting i.e. api/*.js is probably not a good idea.

Depending on what your need are, we could export a few functions with documented/stable APIs. Maybe that can be discussed in a separate issue and we can close this PR for now?

[matthewvolk]

We cannot make this work unfortunately, the open-next.config.ts is compiled at build time to both the edge and node runtime.

I ran into this issue ultimately, and agree that James's solution is probably the best for now. We've actually even been able to work around this for now by writing the open-next.config.ts file at the beginning of our build command, and then rm'ing it at the end. Not the most elegant solution, but does work.

I think best path forward for this PR is to close it, and I can either open an issue or a different PR helping push the "custom config path" solution forward 😄

Thank you all a bunch for your help 🙏

[james-elicx]

I think best path forward for this PR is to close it, and I can either open an issue or a different PR helping push the "custom config path" solution forward 😄

I'll look at making the necessary changes for it this week.