\n Freestyle · Docs · Discord\n
\n\nCloudstate is a JavaScript database runtime. It is a foundational component of Freestyle's full stack JavaScript hosting.\n\n> [!TIP]\n> Try out cloudstate via a freestyle template. Read our [getting started](https://docs.freestyle.dev/getting-started/intro) guide to learn more.\n\n> [!IMPORTANT]\n> If you find a bug in cloudstate, the fastest way you can get it fixed is by contributing a failing JavaScript test. See our [testing for js developers guide](TESTING_FOR_JS_DEVELOPERS.md).\n\nIf you're interested in learning more about how cloudstate works behind the scenes, read on.\n\nYou can install the cloudstate cli alongside the freestyle cli. Run `npm install -g freestyle-sh@beta` or you can build it from source.\n\n### `cloudstate run ./script.js`\n\nThe lowest level way to store data in cloudstate is via the `cloudstate run` command. You can use the global `setRoot` function with an id and object to store data.\n\n```ts\nconst object = {\n counter: 0,\n};\n\nsetRoot(\"test-root\", object);\n```\n\nTo retrieve an object from the database, call `getRoot` and pass in the identifier you used to store the object.\n\n```ts\nconst object = getRoot(\"test-root\");\n```\n\nIf you have multiple references to the same object, those references will be preserved. The values of each property are also lazy loaded, so you don't need to worry about the complexity of objects stored in a single `setRoot` call.\n\n```ts\nconst obj = {};\nconst objects = {\n a: obj,\n b: obj,\n};\n\nsetRoot(\"objects\", objects);\n```\n\n```ts\nconst objects = getRoot(\"objects\");\nobjects.a === objects.b; // true\n```\n\n### `cloudstate serve ./script.js`\n\nA more structured way to store data in cloudstate is via the `cloudstate serve` command. Instead of writing what the script should execute, you write classes. When you put a static id on a class, it will be automatically constructed and stored using `setRoot` for you. Methods will be exposed as endpoints which you can call via http.\n\n```ts\nexport class CounterCS {\n static id = \"counter\";\n count = 0;\n\n increment() {\n return ++this.count;\n }\n}\n```\n\n```\ncurl -X POST http://localhost:3000/cloudstate/instances/counter/increment -H \"Content-Type: application/json\" -d '{\"params\": []}'\n```\n\n### `npx freestyle dev`\n\nThe highest level api is built into freestyle's dev tooling. You can define classes anywhere in a full stack project using a decorator and they be automatically compiled into a single file and served.\n\n```ts\nimport { cloudstate } from \"freestyle-sh\";\n\n@cloudstate\nclass CounterCS {\n static id = \"counter\";\n count = 0;\n\n increment() {\n return ++this.count;\n }\n}\n```\n\nThen you can easily query that data using `useCloud`.\n\n```ts\nimport { type CounterCS } from \"./schema.js\";\nimport { useCloud } from \"freestyle-sh\";\n\nconst counter = useCloud