# Write Cloud Run functions

Cloud Run functions supports writing source code in
[a number of programming languages](https://docs.cloud.google.com/functions/1stgendocs/concepts/execution-environment.md.txt#runtimes).
The language runtime you choose and the type of function you want to write
determine how to structure your code and implement your function. This page
provides an overview of the types of Cloud Run functions and expectations for
source code.

## Types of Cloud Run functions

There are two types of Cloud Run functions:

- **HTTP functions** , which handle HTTP requests and use
  [HTTP triggers](https://docs.cloud.google.com/functions/1stgendocs/calling/http.md.txt). See
  [Write HTTP functions](https://docs.cloud.google.com/functions/1stgendocs/writing/write-http-functions.md.txt)
  for information about implementing HTTP functions.

- **Event-driven functions** , which handle events from your cloud environment
  and use event triggers as described in
  [Cloud Run functions triggers](https://docs.cloud.google.com/functions/1stgendocs/calling.md.txt). See
  [Write event-driven functions](https://docs.cloud.google.com/functions/1stgendocs/writing/write-event-driven-functions.md.txt)
  for information about implementing event-driven functions.

Use an HTTP function when you need your function to have a URL endpoint and
respond to HTTP requests, such as for webhooks. Use an event-driven function
when your function should be triggered directly in response to events within
your Google Cloud project, such as messages on a Pub/Sub topic or changes
in a Cloud Storage bucket.

## Source directory structure

In order for Cloud Run functions to locate your function definition, each
language runtime has requirements for structuring your source code. The basic
directory structure for a function in each runtime is shown below.

### Node.js

The basic directory structure for Node.js functions is as follows:

```
.
├── index.js
└── package.json
```

By default, Cloud Run functions attempts to load source code from a file
named `index.js` at the root of your function directory. To specify a different
main source file, use the `main` field in your `package.json` file.

Your `package.json` file must also include the
[Functions Framework for Node.js](https://github.com/GoogleCloudPlatform/functions-framework-nodejs)
as a dependency:

```json
{
  "main": "index.js",
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  }
}
```

> [!NOTE]
> **Note:** You can add the Functions Framework dependency with [npm](https://www.npmjs.com/) by running `npm install @google-cloud/functions-framework`.

The code in your main file must define your [function entry point](https://docs.cloud.google.com/functions/1stgendocs/writing.md.txt#entry-point)
and can import other code and Node.js modules as normal. The main file can also
define multiple function entry points that can be deployed separately.

### Python

The basic directory structure for Python functions is as follows:

```
.
├── main.py
└── requirements.txt
```

Cloud Run functions loads source code from a file named `main.py` at the
root of your function directory. Your main file must be named `main.py`.

Your `requirements.txt` file must include the
[Functions Framework for Python](https://github.com/GoogleCloudPlatform/functions-framework-python)
as a dependency:

```python
functions-framework==3.*
```

The code in your `main.py` file must define your
[function entry point](https://docs.cloud.google.com/functions/1stgendocs/writing.md.txt#entry-point) and can import other code and external
dependencies as normal. The `main.py` file can also define multiple function
entry points that can be deployed separately.

### Go

The basic directory structure for Go functions is as follows:

```
.
├── myfunction.go
└── go.mod
```

Your function must be in a Go package at the root of your project. The package
and its source files can have any name, except your function cannot be in
`package main`. If you need a `main` package, for example for local testing,
you can create one in a subdirectory:

```
.
├── myfunction.go
├── go.mod
└── cmd/
    └── main.go
```

Your `go.mod` file must include the
[Functions Framework for Go](https://github.com/GoogleCloudPlatform/functions-framework-go)
as a dependency:

```go
module example.com/my-module

require (
  github.com/GoogleCloudPlatform/functions-framework-go v1.5.2
)
```

> [!NOTE]
> **Note:** You can add the Functions Framework dependency by running `go get github.com/GoogleCloudPlatform/functions-framework-go`.

The code in your root package must define your
[function entry point](https://docs.cloud.google.com/functions/1stgendocs/writing.md.txt#entry-point) and can import other code from subpackages
and dependencies as normal. Your package can also define multiple function
entry points that can be deployed separately.

> [!NOTE]
> **Note:** For an example of setting up a basic Cloud Run functions project in Go, see the [Functions Framework for Go Quickstart on GitHub](https://github.com/GoogleCloudPlatform/functions-framework-go#quickstart-hello-world-on-your-local-machine).

### Java

The basic directory structure for Java functions is as follows:

```
.
├── pom.xml
└── src/
    └── main/
        └── java/
            └── MyFunction.java
```

Your Java source files must be under the `src/main/java/` directory and can have
any name. If your source files declare a package, add an extra directory under
`src/main/java` with the name of the package:

```
.
├── pom.xml
└── src/
    └── main/
        └── java/
            └── mypackage/
                └── MyFunction.java
```

We recommend putting associated tests under a `src/test/java/` subdirectory.

> [!NOTE]
> **Note:** If you're working with another JVM language (such as Groovy, Kotlin, or Scala), rename the `java` directories to language-appropriate names (such as `groovy`, `kotlin`, or `scala`).

Your `pom.xml` file must include the
[Functions Framework for Java](https://github.com/GoogleCloudPlatform/functions-framework-java)
as a dependency:

```xml
...
    <dependency>
      <groupId>com.google.cloud.functions</groupId>
      <artifactId>functions-framework-api</artifactId>
      <version>1.0.4</version>
    </dependency>
...
```

The code in your source files must define your
[function entry point](https://docs.cloud.google.com/functions/1stgendocs/writing.md.txt#entry-point) and can import other code and external
dependencies as normal. Your source files can also define multiple function
entry points that can be deployed separately.

### C#

The basic directory structure for .NET functions is as follows:

```
.
├── MyFunction.cs
└── MyProject.csproj
```

You can structure your projects as you would any other .NET source code.
Your source files can have any name.

> [!NOTE]
> **Note:** The same pattern applies if you use F# or Visual Basic, but with appropriate file extensions (`.fs` and `.fsproj` for F#, `.vb` and `.vbproj` for Visual Basic).

Your project file must include the
[Functions Framework for .NET](https://github.com/GoogleCloudPlatform/functions-framework-dotnet)
as a dependency:

```xml
...
    <PackageReference Include="Google.Cloud.Functions.Hosting" Version="1.0.0" />
...
```

The code in your source files must define your
[function entry point](https://docs.cloud.google.com/functions/1stgendocs/writing.md.txt#entry-point) and can import other code and external
dependencies as normal. Your source files can also define multiple function
entry points that can be deployed separately.

You can also
[use the Cloud Run functions template package for .NET](https://docs.cloud.google.com/functions/1stgendocs/concepts/dotnet-langs.md.txt#templates)
to generate the required files.

> [!NOTE]
> **Note:** For information about file structure in relation to functions that use multiple local .NET projects, see [Deploying a function with a local project dependency](https://github.com/GoogleCloudPlatform/functions-framework-dotnet/blob/main/docs/deployment.md#deploying-a-function-with-a-local-project-dependency).

### Ruby

The basic directory structure for Ruby functions is as follows:

```
.
├── app.rb
├── Gemfile
└── Gemfile.lock
```

Cloud Run functions loads source code from a file named `app.rb` at the
root of your function directory. Your main file must be named `app.rb`.

Your `Gemfile` file must include the
[Functions Framework for Ruby](https://github.com/GoogleCloudPlatform/functions-framework-ruby)
as a dependency:

```ruby
source "https://rubygems.org"
gem "functions_framework", "~> 1.0"
```

> [!NOTE]
> **Note:** You can add the Functions Framework dependency with [Bundler](https://bundler.io/) by running `bundle add functions_framework`.

The code in your `app.rb` file must define your
[function entry point](https://docs.cloud.google.com/functions/1stgendocs/writing.md.txt#entry-point) and can import other code and external
dependencies as normal. The `app.rb` file can also define multiple function
entry points that can be deployed separately.

### PHP

The basic directory structure for PHP functions is as follows:

```
.
├── index.php
└── composer.json
```

Cloud Run functions loads source code from a file named `index.php` at the
root of your function directory. Your main file must be named `index.php`.

Your `composer.json` file must include the
[Functions Framework for PHP](https://github.com/GoogleCloudPlatform/functions-framework-php)
as a dependency:

```json
{
  "require": {
    "google/cloud-functions-framework": "^1.1"
  }
}
```

> [!NOTE]
> **Note:** You can add the Functions Framework dependency with [Composer](https://getcomposer.org/) by running `composer require google/cloud-functions-framework`.

The code in your `index.php` file must define your
[function entry point](https://docs.cloud.google.com/functions/1stgendocs/writing.md.txt#entry-point) and can import other code and external
dependencies as normal. The `index.php` file can also define multiple function
entry points that can be deployed separately.

If you are thinking of grouping multiple functions into a single project, be
aware that every function may end up sharing the same set of dependencies.
However, some of the functions may not need all of the dependencies.

Where possible, we recommend splitting up large multi-function codebases and
putting each function in its own top-level directory as shown above, with its
own source and project configuration files. This approach minimizes the number
of dependencies required for a particular function, which in turn reduces the
amount of memory your function needs.

## Function entry point

Your source code must define an *entry point* for your function, which is the
particular code that is executed when the Cloud Run function is invoked.
You specify this entry point when you deploy your function.

How you define the entry point depends on the language runtime you use. For some
languages, the entry point is a function, whereas for others the entry point is
a class. To learn more about defining entry points and implementing
Cloud Run functions in different languages, see
[Write HTTP functions](https://docs.cloud.google.com/functions/1stgendocs/writing/write-http-functions.md.txt)
and
[Write event-driven functions](https://docs.cloud.google.com/functions/1stgendocs/writing/write-event-driven-functions.md.txt).

## Dependencies

You can manage dependencies using standard tools for each runtime. For more
information, see the appropriate page:

- [Specifying dependencies in Node.js](https://docs.cloud.google.com/functions/1stgendocs/writing/specifying-dependencies-nodejs.md.txt)
- [Specifying dependencies in Python](https://docs.cloud.google.com/functions/1stgendocs/writing/specifying-dependencies-python.md.txt)
- [Specifying dependencies in Go](https://docs.cloud.google.com/functions/1stgendocs/writing/specifying-dependencies-go.md.txt)
- [Specifying dependencies in Java](https://docs.cloud.google.com/functions/1stgendocs/writing/specifying-dependencies-java.md.txt)
- [Specifying dependencies in .NET](https://docs.cloud.google.com/functions/1stgendocs/writing/specifying-dependencies-dotnet.md.txt)
- [Specifying dependencies in Ruby](https://docs.cloud.google.com/functions/1stgendocs/writing/specifying-dependencies-ruby.md.txt)
- [Specifying dependencies in PHP](https://docs.cloud.google.com/functions/1stgendocs/writing/specifying-dependencies-php.md.txt)

## Next steps

- Learn how to [write HTTP functions](https://docs.cloud.google.com/functions/1stgendocs/writing/write-http-functions.md.txt).
- Learn how to [write event-driven functions](https://docs.cloud.google.com/functions/1stgendocs/writing/write-event-driven-functions.md.txt).
- Learn about [Cloud Run functions triggers](https://docs.cloud.google.com/functions/1stgendocs/calling.md.txt).