panzacoder•9mo ago

Hello world! 👋

Hello world! 👋 I recently started using Convex for two different NextJS projects and been really enjoying it so far. One thing that has been a little confusing the deeper in I get is the convex-helpers package. It's really helpful at reducing duplication, but it feels odd that it's not deeply referenced/built into the docs. It actually introduces some new patterns for defining schemas/building functions that aren't really talked about at all int he docs. One of the things I like the most about Convex is how complete, cohesive, and straightforward the docs are. So to now have a second source of truth to reference when building out my convex-functions is not as great for me. I know it's not all that different, but here's an example that I don't love. Defining Tables Docs

export default defineSchema({
  users: defineTable({
    name: v.string(),
    tokenIdentifier: v.string(),
  }).index("by_token", ["tokenIdentifier"]),

export default defineSchema({
  users: defineTable({
    name: v.string(),
    tokenIdentifier: v.string(),
  }).index("by_token", ["tokenIdentifier"]),

Helpers

import { Table } from "convex-helpers/server";

export const Users = Table("users", { 
  name: string,
  tokenIdentifier: string,
});

export default defineSchema({
  users: Users.table.index("tokenIdentifier", ["tokenIdentifier"]),
});

import { Table } from "convex-helpers/server";

export const Users = Table("users", { 
  name: string,
  tokenIdentifier: string,
});

export default defineSchema({
  users: Users.table.index("tokenIdentifier", ["tokenIdentifier"]),
});

So, there's a whole separate set of tools and syntax for defining tables available in the helpers, I found that only by reading the code referenced by an example referenced by the withUser hook. And now I have like 2-3 blog posts to read to find out what the most up-to-date best practice is. I kind of loved the simplicity of the docs, but now I'm afraid that I don't know what is up to date and what's not. Any thoughts about my take here? Should I take convex-helpers/Stack posts with a grain of salt because they aren't evergreen, or should I be looking there for the best approach to new problems?

3 Replies

jamwt•9mo ago

@panzacoder hey! convex-helpers and other libraries/practices we outline on stack are ways to test out and iterate with different approaches over time with the dev community we're actually going to start "graduating" some common, popular, successful subset of things from convex-helpers and start moving them into a standard library that's maintained by the platform eng team. then, we'll update the docs to recommend these practices on the "default path" but there will always be new things we're piloting and iterating on in convex-helpers and other places, like convex-ents the stuff that appears in the docs, and the convex package, and future @convex/xxx packages represent the "LTS" parts of the platform we just take awhile to bake/mature things because we have a very high bar for those and will take the maintenance/compatibility responsibility very seriously for those things lmk if you have any more questions, but very fair to call out this ambiguity right now with convex and all the stuff we put out there!

panzacoderOP•9mo ago

That is super helpful convex-context @Jamie ! I really like that approach and gives be a good framework to consider these approaches. I still think your docs are very good, and actually this makes your methodology for creating new stuff super clear to me and increases my trust in the docs to know you have pipeline for new approaches graduating into the mainline. Thank you!

ian•9mo ago

I'd also recommend jumping into the code of any helpers you like but aren't sure about using wholesale - most are a small amount of code that can be copied / pattern-matched where you need. The most useful part of them is getting the generic types right. The hope is that with the helpers you're not too far away from the vanilla syntax / concepts, but keep me honest wherever it feels too wacky. We're also planning some improvements to the built-in package that will allow the Table helper in particular to be not as necessary, by exposing a table's validators more directly. I'll be publishing some demos using my opinionated organization. Ultimately, once your app gets big, you'll decide how you want to organize your code (e.g. pulling table definitions out to separate files). convex-helpers is a proving ground that you can build opinionated abstractions without modifying the core primitives.

Hello world! 👋

Did you find this page helpful?