docs - createCookieSessionStorage says commitSession not needed

[penx]

The docs for createCookieSessionStorage state:

With other session storage strategies you only have to commit it when it's created

https://remix.run/docs/en/main/utils/sessions#createcookiesessionstorage

When we moved from createCookieSessionStorage to another storage solution (vercel kv), we followed this advice and removed calls to commitSession (assuming it was not needed, and that session.set would be all that is required) but it resulted in sessions not being saved.

Elsewhere in the docs for createSessionStorage:

updateData will be called from commitSession

https://remix.run/docs/en/main/utils/sessions#createsessionstorage

Which seems to imply that anything based on createSessionStorage will require a call to commitSession in order to update the session, and I'm fairly sure explains why we would have bugs when removing calls to commitSession.

I think the docs for createCookieSessionStorage should instead state

With other session storage strategies you only have to send an updated cookie in the request header when it's created

I'll raise a PR to the docs for this.

[kiliman]

Yes, the documentation needs to be corrected. For the session API, all session storage providers require you to call commitSession after mutation.

I think what the documentation was alluding to was you don't have to return a set-cookie header in the response after every commit, just the initial one.

In cookie session storage, the session data is stored entirely in the cookie, so any changes require you to send an updated cookie via the set-cookie header.

However, in other storage providers like Cloudflare KV or file-based sessions, the only thing stored in the cookie is the session ID. You would send that id in the set-cookie header on creation. The session ID is used to look up the session in the storage. Since the session id never changes, you don't need to keep sending a set-cookie header.

[penx]

@kiliman thanks, I raised a PR here along those lines. Let me know if you have a suggestion on wording https://github.com/remix-run/remix/pull/9445

[akomm]

Might be related with this issue? Its about memory / custom storage, but looks like same sort of problem with the behavior and documentation: https://github.com/remix-run/remix/discussions/9338