The Convex npm package and the Convex platform have reached 1.0. We're proud to be reaching this milestone and are excited about what's next. It's a good time to reflect on the motivations for and aims of Convex, so see CEO Jamie's post for just that.
The big feature of this release is the version number: for the most part 1.0 is a new name for 0.19 (thanks to everyone who helped us test 1.0 release candidates!) but a few new features made it in.
- Semantic versioning and wire compatibility guarantees
npx convex devhas new flags:--runand--until-success- Expanded valid character set for cron identifiers
- Encouraging React 18 and TypeScript 5.0.3, requiring Node.js v16.15
Leaving 0.x
What does 1.0 mean? Convex has pulled the double-edged sword of semantic versioning from its stone. It's difficult for a platform with a lot of API surface area to guarantee no breaking changes until a major version number. That's why TypeScript doesn't do it! But it communicates an important guarantee to users: you can upgrade without thinking about it.
In order to provide this guarantee for the stable parts of the platform we've designated some features as beta, which we reserve the ability to change without incrementing the major version number. Search, file storage, pagination, data export, optimistic updates, and the Airbyte integration are beta features and are marked this way in the docs. You can use these features (many users do!) but you may have to change e.g. the full text search query syntax when upgrading from Convex 1.4 to 1.5.
Along with the npm package, the Convex platform has reached 1.0. Convex backends will now maintain wire protocol compatibility so clients will continue to work without requiring updates. Convex backends will continue to run Convex functions the same way with exceptions for implementing JavaScript runtime APIs that currently throw "not implemented" exceptions. These guarantees amount to a promise to keep applications deployed to Convex running for the foreseeable future.
New convex dev command line flags
Sometimes it's useful to run initialization when booting up a development session, especially the first time when the development deployment is a blank slate. Once convex dev completes a successful code push it will (repeatedly if it fails) run a function if specified with the --run flag.
You can do anything in this function to help the developer set up their instance:
- Check for environment variables and error if they are not present
- Seed the database with starter data
- Call a third party service to make sure it's correctly set up
Since this function will run again if it fails, you should avoid running side effects you don't want to run many times in this function.
Another new flag --until-success can be used to stop watching the filesystem after the first successful deployment (and function --run if specified). This is useful in an npm run dev script to wait for the backend to be ready before starting the frontend development server.
Encouraging TypeScript 5.0.3 and React 18, requiring Node.js v16.15
Convex can be used with TypeScript 4.7 and above, but works best with 5.0.3. Convex's React bindings still support React 17, but we're considering features that won't.
The Node.js version is a hard requirement: it's good to be updating anyway for security fixes, but the Convex CLI now uses features added in this minor version. Note that Node.js 16 is scheduled for end-of-life in September of this year, at which point we will raise this requirement to Node 18.
Expanding the character set for cron identifiers
It's a small change, but it's come up enough to mention: now you can use all non-control ASCII characters when naming your cron jobs. You can finally write a cron job called "Send reactivation emails! $$$".
Onwards to Convex 1.1
Thanks for being with us on this journey. We're excited about all the features that are still yet to be released and hope you are too. Happy building.
