Migrating from v1 to v2
Have you run into something that’s not covered here? Add your changes to GitHub! (opens in a new tab)
Introduction
This is a reference for upgrading your Pylon from v1 to v2. Version 2 introduces the support for various runtimes, a new npm create command, and an improved development server.
The official supported runtimes by the npm create pylon
command are Bun, Node.js and Cloudflare Workers. Other runtimes are also supported but require manual setup.
If you’re curious what’s new, head over to the v2.0 Release Notes.
For most users we expect a smooth upgrade path as only a couple of changes will be required:
Updating your dependencies
You need to update your dependencies to the latest version of Pylon. The @getcronit/pylon-cli
and @getcronit/pylon-server
are no longer required and replaced by the @getcronit/pylon-dev
package.
Update Pylon version
{
"dependencies": {
"@getcronit/pylon": "^2.0.0"
}
}
Replace old dependencies with pylon-dev
{
"devDependencies": {
- "@getcronit/pylon-cli": "^1.0.0",
- "@getcronit/pylon-server": "^1.0.0"
+ "@getcronit/pylon-dev": "^2.0.0"
}
}
Updating scripts
Pylon v2 introduces a new pylon dev
command that handles multiple runtimes.
You can choose your specific start command by using -c <command>
.
Update your start script
{
"scripts": {
- "develop": "bun run pylon develop"
+ "dev": "pylon dev -c 'bun run .pylon/index.js'"
}
}
Update your build script
{
"scripts": {
- "build": "bun run pylon build"
+ "build": "pylon build"
}
}
Handling breaking changes
Next, we’ll cover the breaking changes that you might encounter when upgrading to Pylon v2. In order to successfully update, you’ll need to resolve these changes.
GraphQL definition
We have updated the way you define your GraphQL schema. Instead of the default export of the defineService
function you now have to export a graphql
object.
This allows for supporting multiple runtimes that depend on the default export.
Before
import { defineService } from "@getcronit/pylon";
export default defineService({
graphql: {
Query: {
sum: (a: number, b: number) => a + b,
},
Mutation: {
divide: (a: number, b: number) => a / b,
},
},
});
After
import { app } from "@getcronit/pylon";
export const graphql = {
Query: {
sum: (a: number, b: number) => a + b,
},
Mutation: {
divide: (a: number, b: number) => a / b,
},
};
export default app;
Custom routes and middleware
The app
instance is now used to define custom routes and middleware. This change allows for a more flexible API and better integration with the underlying runtimes.
Before
import { PylonAPI } from "@getcronit/pylon";
export const configureApp: PylonAPI["configureApp"] = (app) => {
app.get("/hello", (ctx, next) => {
return new Response("Hello, world!");
});
};
After
import { app } from "@getcronit/pylon";
app.get("/hello", (ctx, next) => {
return new Response("Hello, world!");
});
Logging
The logger
instance has been removed due to the lack of customizability. We are still looking into a better solution for logging in the future.
If you know of a good solution, please let us know (opens in a new tab).
Instead of using the logger
instance, please use console
for logging, or your favorite logging library.
- import { logger } from "@getcronit/pylon";
- logger.info("Hello, world!");
+ console.log("Hello, world!");
Client Generation (GQty)
You only need to update the client generation if you are using the feature described in the Client Generation guide.
{
- "pylon": {
- "gqty": "./frontend/src/gqty/index.ts"
- },
"scripts": {
- "dev": "pylon dev -c 'bun run .pylon/index.js'",
+ "dev": "pylon dev -c 'bun run .pylon/index.js' --client --client-path ./frontend/src/gqty/index.ts --client-port 3000",
}
}
Dockerfile
If you are using a Dockerfile to build your Pylon project, you need to update the ENTRYPOINT
to replace the pylon-server
command.
- ENTRYPOINT [ "bun", "run", "./node_modules/.bin/pylon-server" ]
+ ENTRYPOINT [ "bun", "run", "/usr/src/pylon/.pylon/index.js" ]
Conclusion
We hope this guide has helped you upgrade your Pylon project to v2. If you have any questions or need further assistance, feel free to reach out to us on Discord or GitHub.