One Month of SolidStart Beta 2

[ryansolid]

It was almost a year ago I wrote one month into our first SolidStart beta and I can already see the differences this time around. That being said we are still working through bugs and there are things we have learned we need to address. This time categorically at least the list is a lot smaller which gives me a lot more confidence in direction.

Last time we had hundreds of issues flying in very early on, more than we could keep on top of. This time things have flowed in a more controlled manner. Partially because we probably didn't push this release as hard, but also because I think we've handled a lot of the issues we had faced previously.

In any case, I want to capture our current observations and talk about how we should address them on our path to getting SolidStart to RC.

As always I want to put ideas out there early rather than suggest I have the solution. So if you have thoughts on these topics please join the discussion.

Topics

1. API Routes need to be separated out

I know this goes against what people have come to expect in these FS routing systems, but trying to merge it is paddling upstream. SolidStart is client router independent. This means:

• The logic for routing is handled by the router and any logic for API routes is going to be different. I needed to duplicate matching logic from Solid Router to get the feature working.
• API routes don't need all the features.. Things like route groups/nesting make no sense so again there is more odd logic there.
• Page routes can be modified before being passed into the router, they can be nested and inserted multiple times (say for i18n), extra routes can be added. We do not have the information until we hit rendering the page to know what routes we are dealing with.

Ultimately they are handled separately. There is no way to rank them together. Routes and APIs sitting in the same folder might not even be at the same path. That is confusing. This is the tradeoff of the flexibility of our design. So I'm suggesting we pull them out into their own folder separate from /routes. Do we name it /api? Probably. Does it always prefix with /api to reduce chance of collision? Maybe not. But we will need to process API routes first and fallback to pages on a miss if we don't.

2. Base Path Fiasco

A couple of these topics will be related to Vinxi and this is one. There is a conceptual difference between the base path of your server and where assets live which was overlooked. This has caused some weird asset mismatching and we need to come up with a definitive answer to this.

To add wound to injury the new Solid Router (v0.10) improved dev experience at the cost of losing the ability to apply the base path directly in lowercase <a> tags. This was an oversight on the design enough that we probably should consider moving back to <A> and previous conventions. So focused on the final prize that this critical case was missed. Router fixes can happen independent of Start's release but we should try to synchronize it for the initial 1.0 release.

These are all addressable but will probably need some slight API tweaks.

3. To Wrap or Not to Wrap

SolidStart has taken the position of not wrapping anything it doesn't need. Things like @solidjs/router and @solidjs/meta are not re-exported anymore. SolidStart uses a lot of technology under the hood beyond SolidJS. Vite, Nitro, H3, Vinxi, Seroval. The relationship with Seroval is pretty simple because Solid uses it internally and Start leveraging the same plugins and capability just lines up. However, the others are more complicated to balance. They have their own plugin systems, conventions, and runtimes.

Config

Our plan has to use the familiar Vite config as the entry point to Start since it is already designed to handle things being built for both the client and the server. One config to feed into the corresponding vite builds with a few modifications for the specific process under the hood. It turns out that this doesn't always work well as sharing the same plugin across builds can be problematic. Of course we can modify to wrapping plugins in a function. But these gaps also impact other configuration. Things like base which we talked about in the previous section.

Similar concern with start.server, the Nitro config. Presumably not all settings in Nitro config will work through Vinxi which needs to modify settings to pull the whole thing together. Also because Vinxi doesn't use Nitro during dev (more on this later).

Server Utilities

Nitro uses H3 as does Vinxi's dev server. However H3 has its own event which is different than Solid's getRequestEvent. Solid having a standardized event is important for the ecosystem so libraries like the Router/Meta etc have a common interface. This is how we can make things like Start not tied to a specific library. But also is why we can't just adopt H3's event. This works really well for reading the incoming Request. Afterall you don't modify the Request and using a standard WebRequest makes a lot of sense.

Unfortunately Response objects can only modify certain things once created. Making it awkward for APIs that would seek to construct them on the fly. H3 offers several methods for modifying the response. The methods are very functional and all take H3's event as the first argument. Like setHeader(event, "x-foo", "some-value"). Attempting to juggle both events is very awkward, so I merged our events. But this is probably a mistake. Types are merged and it is a bit of a mess.

The options here are tricky though because the best we can really do otherwise is either grab the H3 event off our event like:

setHeader(event.h3Event, "x-foo", "some-value")

Or have to wrap all the H3 methods ourselves. Either to accept our event or use AsyncLocalStorage so you wouldn't pass an event into them directly. Async Local Storage might be the ideal solution to our problem but not all platforms support it properly, and going this approach universally might make that a bit buggy. Biggest gaps are Cloudflare requires special config, and Stackblitz doesn't seem to work. This has delayed H3 implementing this themselves. But an awkward wait when we are trying to stabilize. Is it best to just wrap ourselves?

I will also mention that circular references around our re-export of wrapping and our FileSystem routes caused some hard to pin down bugs. I pulled createHandler into its own entry but arguably perhaps the utility methods should have been the ones that moved.

Dev Runtime

Vinxi doesn't run Nitro in dev which is an interesting tradeoff. Part of it is Vinxi keeps a certain separation that speeds up HMR a bit. But more so to have a common pipeline of plugins before Nitro is ever in the picture.

But it also blocks/delays us from certain Nitro features. If you look at the Nitro docs they have their own conventions for middleware/api routes. Nuxt honors them and exposes it through a /server folder. This lets Nitro maximize it. But it is also fairly opinionated using different file conventions like hello.get.ts, automatic imports etc...

Vinxi seeks to put the convention in the consumer(Ie SolidStart's) hands to provide a consistent experience, while full Nitro usage seeks to own part of the experience. It is obviously attractive to wrap things in a consistent experience as it makes thing intuitive, but it also prevents one from just sending people to all the various other documentation sites on how to use the finished product.

4. Streaming is a new Frontier

Finally, Beta 2 changed the default of SSR to streaming from Async. This is generally a good thing but it has revealed some more bugs in Solid that we hadn't hit previously now that there are more eyes on it. I don't believe this is a blocker just something we need to be aware of as we approach bug fixes.

Conclusion

There is still some things to figure out, but fortunately none of the topics are the same ones we had last time around. I intend to do updates like this more often this time around. We've added changesets to the repo to better track changes. We are ramping up to 1.0 and we will need everyone's help. Thank you for building with Solid and SolidStart!

[atk]

Re: config: This is probably related to vinxi, but we overwrite the vite mode, so we are losing the capability to use different environments. Without this capability, we will also need a vitest config and having multiple configurations for the same thing is always prone to errors.

Our communication of breaking changes during this second beta was also less than ideal. We should probably add a pinned post to the discord channel for solid start.

Otherwise, I think we're on a good path to 1.0.

[birkskyum]

Or have to wrap all the H3 methods ourselves.

It does indeed sound like the right approach to have an adapter for the H3 events instead of an awkward wait. If they stabilize in the future on i.e. AsyncLocalStorage / WebStandard request+response, the adapter can always be pulled out if obsolete.

[birkskyum]

concern with start.server, the Nitro config

nitro.config.ts - It's not clear if start.server refers to vinxi's chosen dev server (vite) or the prod server (nitro). It could make sense to either:

1. rename start.server to start.nitro
2. have nitro.config.ts separate
3. (do like nuxt - example below) rename vite.config.ts to i.e. solidstart.config.ts or vinxi.config.ts, and put nitro to root level

For inspiration, this is i.e. how nuxt does it in nuxt.config.ts, which i find is very intuitive:

export default defineNuxtConfig({
  nitro: {
    // nitro options
  },
  vite: {
    // vite options
  }
})

or analog (vite.config.ts):

export default defineConfig({
  plugins: [
    analog({
      nitro: {
        preset: 'node-server',
      },
    }),
  ],
});

... maybe it could also help distinguish the base path options a bit

[ryansolid]

I think I like the idea of Start depending directly on Vinxi. If there isn't concern with CLI commands working etc (I've seen some weird stuff here) I think that makes a lot of sense.

[nksaraf]

Yeah I think it's a sane choice. CLI could be a problem if solid start doesn't want to wrap the cli

[birkskyum]

from discord - real world version mismatch issues

[nksaraf]

Yeah I thought people will would not get it because we are on 0.1.x but yeah I have no problem with making it a dependency as long as the cli works .. or Vinxi can export a createCLI command that can be used to create an identical cli but solid branded

[ryansolid]

It's more than just the CLI I think though.. Now that we don't wrap H3 helpers either my gut is that we can't do it this way. Atleast not for all package managers. NPM used to at least be fine with depending on a dependency of a dependency but I'm positive PNPM isn't.

[birkskyum]

full Nitro usage seeks to own part of the experience

It could indicate that Nitro is still too opinionated at this point, which makes sense given that it's only been used by one framework this far (Nuxt), and now it comes to the test if it's flexible enough for more (Vinxi) or if it needs some adjustments. So it's better to push Nitro towards being less opinionated than to have it force-fit everything to be the same as how Nuxt/Nitro are today, even if it means we for now can't use all the nitro options found on their website.

[nksaraf]

Totally agree. With Vinxi, one of the fundamental ideas is push eeverything (or much as I can) to runtime considerations. That means things like file conventions and stuff are DX optimizations for the runtime behaviour provided by us and you are free to have your opinions there (its usually where people have the most opinions, analogy: everybody has an opinion on laying out icons on your iOS homescreen. You are not as opinionated about how the clock app works, or the settings screen)

[AlbertSabate]

My two cents after implementing solid-start v0.4.x version.

• Nitro is unflexible and very opinionated. For example, my lambda@edge request, even providing the whole code, it is still stuck in low priority. I had to fork and override nitro to make it work, do your custom handler feels complicated (I could not succeed).
• Have you consider do a monorepo with solid, solid start, router, meta, etc. It would be easier for when researching information, opening bugs, etc.
• I dislike the 'use server' and clientOnly(). It would be easier to have or 'use ...' or fn based, but not both. Feels a bit mixed up now.
• I agree the event is a bit messy now, as you have to differentiate where the event is coming from.
• I still could not find a nice way to send data from SSR to the client from entry-server and middlewares. The current way is with createResource, which does not work on entry-server and middlewares. (Maybe I'm missing something here as docs are not finilised yet)

[lxsmnsyc]

clientOnly was not meant to be the opposite of use server, the upcoming use client is meant for that. clientOnly solves a very different purpose.

[AlbertSabate]

Isn't it confusing, though? Do you know if clientOnly will disappear? How should we use it? (this is the questions that comes to my mind now)

[lxsmnsyc]

No clientOnly won't disappear as it is solving an specific problem. Even NextJS has a similar feature (hello dynamic)

[ryansolid]

1. On Nitro we are going to have this to a certain degree with any solution we try to leverage. There isn't much for it but doing it ourselves and I don't think that is practical. Stuff here may take some time but I know they are very dedicated. Issues will naturally get elevated as need happens as will more people be available to contribute. So this is all positive as we continue to bring more usage to Nitro.

2. Maybe in the future. Different projects with different levels of maturity. I like having separate issues. Personal preference but it keeps things cleaner for me. It is possible with enough maturing stuff like Start or Router could enter Solid mono repo. But currently Solid is the only 1.0 (ie major version) library we have here.

3. @lxsmnsyc did a good job explaining this.

4. Agreed.

5. That being said we do need more middleware docs. We have a locals object on our event which can be set with properties in middleware and then read inside your page/api/server fn code. If the data is available already, perhaps loaded async in middleware, you should be able to just add a script tag in entry-server and then read the data when the page loads. That being said, remember for hydration to work Solid has to render on the server and hydrate in the same way. So data availability should match up. createResource takes care of the majority case so you don't have create/read from script yourself.

[ryansolid]

Ok I've had some time to reflect on the first set of comments and talk to some folks involved. My thinking so far is as follows. Keep in mind this is just a proposal for a v0.5.0 so would love some thoughts.

1. API Routes

We use a /api convention that also applies that to path but we add an apiBase config option to change it /api. This way we are namespace by default but you can change it to whatever you like.

2. Base Path

I'm leaving this to Vinxi to figure out. I think Nikhil is already working on having 2 different options. One for baseUrl and one for asset locations.

3. Wrapping

In general, we are in favor of wrapping. And acknowledging Vinxi as a thing more. Ie.. Vinxi powered by Nitro.

3a Config

Vite config is awkward in that we want plugins to be a function rather than just an array because they can be used in multiple builds. Most Vite settings do work though. But we've forced things like Vitest to require 2nd configs. Any option to move away from vite config (like start.config.ts) does that as well though so I think we are just where we are to a degree. If there is some way to address Vitest I'd love that but I'm not holding my breath. The biggest question is if file is different enough to merit that. SvelteKit, Astro etc have their own configs so there are arguments for it. But I'm leaning on keeping it vite config.

As for start.server I think we should think of it as a vinxi config that happens to let us tap into Nitro presets. We don't really expose Nitro directly and don't have intention of adopting their conventions so this is always going to be a barrier.

3b Server Utils

I think we have SolidStart stop re-exporting them. This fixes our circular dependency setup so we can return to there just being @solidjs/start, @solidjs/start/client and @solidjs/start/server. It also is a nod to perhaps eventually using H3 directly in application code. However, for the short term at least we Vinxi wraps them and we import our utils from vinxi/server. Vinxi will offer an Async Local Storage compatible version that will be able to optionally accept an event. And not just an H3Event but a SolidEvent like we do today, but without mashing the events together. We will manage this using a shared symbol, similar to how RX Observable interop works.

So,

import { setHeader } from "vinxi/server";
import { getRequestEvent } from "solid-js/web";

async function ServerFunc() {
  "user server";
  setHeader("name", "value") // uses AsyncLocalStorage
  
  const event = getRequestEvent(); // uses Solid's Event
  setHeader(event, "name", "value")
  
  event.h3Event // access H3Event directly
  setHeader(event.h3Event, "name", "value") // also works
}

Some naming questions here, like should we use h3Event. There is discussion to obscure that detail but my gut is you only will be using it when you are aiming to use it. In which case it will be specifically an H3 event you are dealing with.

Honestly we think the Async Local Storage API will be prevalent, but in some environments where it doesn't work we will still need to always pass in that optional event as a first argument. And this way in things like middleware you can take the event being passed in and push it straight through.

3c Dev Runtime

Given the other decisions, no change.

4. Streaming is Fun...

Honestly bugs will come in for a while and its a good thing. This is non-blocking.

[jchatard]

1. API Routes

We use a /api convention that also applies that to path but we add an apiBase config option to change it /api. This way we are namespace by default but you can change it to whatever you like.

Agreed

3. Wrapping

Yeah I feel like if people want to use those, let them do. And I think it allows us to acknowledge that start is build with X and Z, and pushes us to learn more about thoses pieces.

3b Server Utils

There is discussion to obscure that detail but my gut is you only will be using it when you are aiming to use it.

100 % agreed

4. Streaming is Fun...

Well, I'm hitting those corners, having really hard times to isolate the sources, and making repro, so I won't say "fun,", but I get the point. 😁

[ryansolid]

Regarding wrapping itis important to note Im suggesting exposing Vinxi more, also pointing to Nitro less directly, since Vinxi wraps it, but doesn't implement all of it.

[jchatard]

That sounds good, as long as we can access what Vinxi laverages. This let us act on it, and avoid making mistakes by using stuff vinxi is not handling or doing differently than Nitro.

[atk]

Maybe the solution for vitest could be not to rely on the mode, but instead use argv to detect if we are called by vitest in the vite plugin. I'll test it later.

[atk]

Unfortunately, this cannot deliver a full solution; it is impossible to test server actions this way. Thus, we need something like vinxi test: nksaraf/vinxi#174

[ryansolid]

I see.. that's good to know thanks for looking into this.

[rvlzzr]

I would like to see the apiBase able take an array of multiple paths. Sometimes legacy/third-party services require things at certain paths (I need to handle webhooks from a certain service directly under /events for example but it doesn't make sense to put API routes that have nothing to do with events there).

I think route groups are useful for API routes -- again if you're handling webhooks or such coming in from multiple services it can be convenient to group them by service.

Not being able to specify a non-html 404 page or mix API and page routes isn't intuitive or ideal but I haven't come across a case where this is a hard requirement... But could there be some "strict filesystem routing" option to tell the server that our router is following filesystem routing conventions and isn't doing anything exotic? Wouldn't such an option make this possible?

[ryansolid]

I was thinking in that case you could opt into no prefix.. and then just have folders that could collide with routes.. and that's on you. I just didn't want to make that default as once you separate them it is less obvious having these collisions.

Good point on route groups for convenience. Part of me was looking at this and wondering if we could basically remove the matching from the FS router and just feed these straight to H3 and let the application server handle the route matching. It would let these routes leverage H3 better. Than being said mapping could still do this without matching. As long as we are not doing scoring and just rely on a collision is an error. The more we push the mapping here into lower level then the more likely we will be able to leverage platform features. Like picture if we want API routes deployed to different serverless functions.

So while yes there could be a mode that is like assume this is strict and merges it all together it ties our hands a bit more I think. Our pages is one platform level route, but then the rest of the handlers should be lower level I think.