where do my convex functions actually run?

[lofty rain]

do the convex functions run on my computer or do they run in convex's cloud? enlighten me on how convex actually works

[vernal hatch]

Hi @lofty rain. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

Convex functions run in the Convex cloud, not on your local computer. They are written in JavaScript or TypeScript and replace a traditional backend. There are three types of functions: Queries, Mutations, and Actions.

• Queries read data from your Convex database and are automatically cached and subscribable (realtime, reactive).
• Mutations write data to the database and run as a transaction.
• Actions can call Open AI, Stripe, Twilio, or any other service or API you need to make your app work[^1^].

Convex functions are executed in a custom JavaScript runtime very similar to the Cloudflare Workers runtime[^2^]. The runtime is always up, ready to handle any function at a moment's notice, and provides low overhead access to your data[^2^].

When a function is executed, it begins a new transaction and executes the function’s JavaScript[^3^]. The function reads from different indexes from the database and builds up the query’s read set. After completely executing the query’s JavaScript, the function runner sends its return value along with its begin timestamp and reads back to the sync worker, which passes the result back to the client over the WebSocket[^3^].

Convex also introduces built-in support for actions — arbitrary lambda functions that run in a Node.js environment on the Convex cloud[^4^]. These actions are Convex’s first foray into executing code that has side-effects or isn’t purely oriented around reading or writing data[^4^].

^1^]: [Functions - Convex (https://docs.convex.dev/functions)
^2^]: [Functions > Runtimes - Convex (https://docs.convex.dev/functions/runtimes)
^3^]: [How Convex Works > Executing a query - Stack (https://stack.convex.dev/how-convex-works#executing-a-query)
^4^]: [Ready for Actions - Stack (https://stack.convex.dev/ready-for-actions)

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@lofty rain kapa.ai is still learning and improving, please let us know how it did by reacting below

[lofty rain]

@vernal hatch give me a detailed overview of how convex works. how do the functions I write get automatically transmitted to convex cloud to be run? and how does my code get back the data. how does it all work?

[vernal hatch]

Let me check the knowledge base for you. One moment! :books:

---

Convex is designed to simplify the development of web applications by providing a global state management system that runs in the cloud. It allows developers to easily build interactive and collaborative applications without managing backend infrastructure[^5^].

Here's a detailed overview of how Convex works:

1. Deploying: You start by deploying your application to Convex and your hosting platform. Your codebase has two halves: the Web app that you build and deploy to your hosting provider and the backend endpoints within convex/ that you push with convex deploy to the Convex cloud[^6^].

2. Serving: Once your app is deployed, it creates a WebSocket connection to your Convex deployment for executing functions on the server and receiving their responses. There are three main pieces of a Convex deployment: the sync worker, which manages WebSocket sessions from clients, the function runner, which runs the functions in your convex/ folder, and the database, which stores your app’s state[^6^].

3. Executing a Query: When you execute a query, the Convex client sends a message on the WebSocket to tell the sync worker to execute this query. The sync worker passes this request along to the function runner[^3^]. The function runner internally maintains an automatic cache of recently run functions, and if the query is already in the cache, it returns its cached value immediately[^3^]. Otherwise, it spins up an instance of the V8 runtime, begins a new transaction, and executes the function’s JavaScript[^3^].

4. Reading and Writing Data: Executing the function reads from different indexes from the database and builds up the query’s read set. After completely executing the query’s JavaScript, the function runner sends its return value along with its begin timestamp and reads back to the sync worker, which passes the result back to the client over the WebSocket[^3^].

5. Transactions: All queries and mutations interact with the database exclusively through transactions: all of the reads and writes in a function’s execution are grouped together into an atomic transaction[^9^]. Convex ensures that all transactions in the system are serializable, which means that their behavior is exactly the same as if they executed one at a time[^9^].

6. Functions: Your function runner uses V8 for executing JavaScript, and since V8 can’t run TypeScript directly, Convex bundles (or compiles) the code in your convex/ directory before sending it to the server for execution[^4^].

^5^]: [Introduction - How Convex Works (https://stack.convex.dev/how-convex-works#introduction)
^6^]: [Overview - How Convex Works (https://stack.convex.dev/how-convex-works#overview)
^3^]: [Executing a query - How Convex Works (https://stack.convex.dev/how-convex-works#executing-a-query)
^9^]: [Transactions - How Convex Works (https://stack.convex.dev/how-convex-works#transactions)
^4^]: [Functions - How Convex Works (https://stack.convex.dev/how-convex-works#functions)

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@lofty rain kapa.ai is still learning and improving, please let us know how it did by reacting below

[lofty rain]

@vernal hatch what's the difference between the convex dev and convex deploy commands? I'm guessin both of them still bundle the typescript files to javscript file before uploading them to the convex cloud?

[vernal hatch]

Let me check the knowledge base for you. One moment! :books:

---

Yes, you're correct. Both npx convex dev and npx convex deploy commands bundle your TypeScript files into JavaScript before uploading them to the Convex cloud[^7^][^10^]. However, they serve different purposes:

1. npx convex dev: This command is used during the development process. It starts a local development server and watches your convex/ directory for changes. When you save a file, it automatically regenerates the generated code (https://docs.convex.dev/generated-api/) in the convex/_generated directory, bundles your Convex functions and their dependencies, and pushes them to your development deployment[^8^].

2. npx convex deploy: This command is used to deploy your Convex functions to production. It performs similar steps as npx convex dev, but it pushes your functions, indexes, and schema to the production deployment[^10^]. The target deployment to push to is determined by the CONVEX_DEPLOY_KEY or CONVEX_DEPLOYMENT environment variables[^10^].

In both cases, Convex uses esbuild (https://esbuild.github.io/) to traverse your convex/ folder and bundle your functions and all of their used dependencies into a source code bundle[^7^].

^7^]: [Bundling for Convex - Functions (https://docs.convex.dev/functions/bundling)
^8^]: [Generated Code - Convex (https://docs.convex.dev/generated-api/)
^10^]: [Deploy Convex functions to production - CLI (https://docs.convex.dev/cli#deploy-convex-functions-to-production)

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@lofty rain kapa.ai is still learning and improving, please let us know how it did by reacting below

[lofty rain]

@vernal hatch what if I want to run and test convex functions? where do I see the result of a console.log?

[vernal hatch]

Let me check the knowledge base for you. One moment! :books:

---

To run and test Convex functions, you can use the built-in console API to understand what's happening inside your functions[^11^]. Here's an example of how to use console.log in a Convex function:

import { mutation } from "./_generated/server";  
import { v } from "convex/values";  
  
export const mutateSomething = mutation({  
  args: { a: v.number(), b: v.number() },  
  handler: (_, args) => {  
    console.log("Received args", args);  
    // ...  
  },  
});  

The output of console.log and other console methods can be viewed in several places:

1. Browser Developer Tools: When using the ConvexReactClient, the logs are sent from your dev deployment to your client, and the client logs them to the browser. Note that production deployments do not send logs to the client[^11^].

2. Convex Dashboard: You can view the logs in your Convex dashboard on the Logs page (https://docs.convex.dev/dashboard/deployments/logs)[^11^].

3. Terminal: You can view the logs in your terminal by running npx convex logs or npx convex dev --tail-logs[^11^].

For scheduled functions, you can view logs from previously executed scheduled functions in the Convex dashboard Logs view (https://docs.convex.dev/dashboard#logs-view)[^12^].

^11^]: [Debugging during development - Functions (https://docs.convex.dev/functions/debugging#debugging-during-development)
^12^]: [Debugging - Scheduled Functions (https://docs.convex.dev/scheduling/scheduled-functions#debugging)

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@lofty rain kapa.ai is still learning and improving, please let us know how it did by reacting below

[lofty rain]

@vernal hatch does npx convex dev only read/monitor files in the convex/ directory or does it also compile my web app files?

[vernal hatch]

Let me check the knowledge base for you. One moment! :books:

---

The npx convex dev command is specifically designed to monitor and compile the files in your convex/ directory[^8^]. When you run this command, it watches the local filesystem for changes in your convex/ directory. When you change a function or the schema, the new versions are pushed to your development deployment and the generated types in convex/_generated are updated[^8^].

It does not compile or monitor your web app files. The compilation and monitoring of your web app files would typically be handled by your web app's build system or development server.

^8^]: [Run the Convex dev server - CLI (https://docs.convex.dev/cli#run-the-convex-dev-server)

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@lofty rain kapa.ai is still learning and improving, please let us know how it did by reacting below

[lofty rain]

@vernal hatch why then does npx convex dev report a typescript error on the svg files saved in the /src/app/assets directly of my project whereas the convex folder is located in /convex/ ?

[vernal hatch]

Let me check the knowledge base for you. One moment! :books:

---

The npx convex dev command is designed to monitor and compile the files in your convex/ directory[^8^]. However, it also follows the imports in those files to bundle that code[^10^]. This means if a file in your convex/ directory imports a file from another directory (like /src/app/assets), npx convex dev will also try to bundle that file.

If you're seeing a TypeScript error on SVG files, it's likely because TypeScript doesn't know how to handle SVG files by default. You might need to add a type declaration for SVG files in your TypeScript configuration.

Here's an example of how you can do this:

1. Create a declarations.d.ts file in your project root or in your types directory if you have one.
2. Add the following code to the declarations.d.ts file:

declare module "*.svg" {
  const content: any;
  export default content;
}

This tells TypeScript to treat SVG files as modules and to not throw any errors when they're imported.

Remember to check your tsconfig.json file to ensure it includes the directory where you placed the declarations.d.ts file.

^8^]: [Run the Convex dev server - CLI (https://docs.convex.dev/cli#run-the-convex-dev-server)
^10^]: [Bundling for Convex - Functions (https://docs.convex.dev/functions/bundling)

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@lofty rain kapa.ai is still learning and improving, please let us know how it did by reacting below

[lofty rain]

@vernal hatch can referencing a function or a variable from any subfolder within /src folder, cause typescript issues with recognizing svg files on the npx convex dev side?

[vernal hatch]

Let me check the knowledge base for you. One moment! :books:

---

Yes, it can. The npx convex dev command bundles your Convex functions and all of their used dependencies into a source code bundle[^10^]. This means if a file in your convex/ directory imports a function or a variable from another directory (like any subfolder within /src), npx convex dev will also try to bundle that file.

If the imported file or any of its dependencies include SVG files, and TypeScript doesn't know how to handle SVG files, you might see TypeScript errors.

To resolve this, you can add a type declaration for SVG files in your TypeScript configuration. Here's how you can do this:

1. Create a declarations.d.ts file in your project root or in your types directory if you have one.
2. Add the following code to the declarations.d.ts file:

declare module "*.svg" {
  const content: any;
  export default content;
}

This tells TypeScript to treat SVG files as modules and to not throw any errors when they're imported.

Remember to check your tsconfig.json file to ensure it includes the directory where you placed the declarations.d.ts file.

^10^]: [Bundling for Convex - Functions (https://docs.convex.dev/functions/bundling)

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@lofty rain kapa.ai is still learning and improving, please let us know how it did by reacting below

[lofty rain]

@vernal hatch what do you mean vy "if the imported file or any of it's dependencies..."?

[vernal hatch]

Let me check the knowledge base for you. One moment! :books:

---

When I say "if the imported file or any of its dependencies include SVG files", I'm referring to the chain of imports that can occur in a JavaScript or TypeScript project.

For example, let's say you have a function in a file convex/myFunction.ts and this function imports a variable from another file src/utils/myVariable.ts like so:

import { myVariable } from '../src/utils/myVariable';

Now, if myVariable.ts itself imports an SVG file:

import mySvg from '../assets/mySvg.svg';

In this case, mySvg.svg is a dependency of myVariable.ts, and indirectly a dependency of myFunction.ts. When you run npx convex dev, it will try to bundle myFunction.ts along with all its dependencies, which includes myVariable.ts and mySvg.svg.

If TypeScript is not configured to handle SVG files, this can lead to errors. That's why you might need to add a type declaration for SVG files in your TypeScript configuration, as explained in the previous responses.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@lofty rain kapa.ai is still learning and improving, please let us know how it did by reacting below

[lofty rain]

@vernal hatch what if myVariable.ts imports func1 from funcs.ts and funcs.ts file imports an svg, is this an issue?

[vernal hatch]

Let me check the knowledge base for you. One moment! :books:

---

Yes, this can be an issue. In this case, the SVG file is an indirect dependency of myVariable.ts and myFunction.ts. Here's how the dependency chain works:

1. myFunction.ts imports myVariable from myVariable.ts.
2. myVariable.ts imports func1 from funcs.ts.
3. funcs.ts imports an SVG file.

When you run npx convex dev, it will try to bundle myFunction.ts along with all its dependencies, which includes myVariable.ts, funcs.ts, and the SVG file.

If TypeScript is not configured to handle SVG files, this can lead to errors. You can resolve this by adding a type declaration for SVG files in your TypeScript configuration:

1. Create a declarations.d.ts file in your project root or in your types directory if you have one.
2. Add the following code to the declarations.d.ts file:

declare module "*.svg" {
  const content: any;
  export default content;
}

This tells TypeScript to treat SVG files as modules and to not throw any errors when they're imported.

Remember to check your tsconfig.json file to ensure it includes the directory where you placed the declarations.d.ts file.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: