Shopify Functions Rust Crate

A crate to help developers build Shopify Functions.

Usage

• The typegen macro allows you to generate structs based on your Function API (based on the provided GraphQL schema) and multiple input queries.
• The shopify_function attribute macro marks the following function as the entry point for a Shopify Function. It manages the Functions input parsing and output serialization for you.
• The run_function_with_input function is a utility for unit testing which allows you to quickly add new tests based on a given JSON input string.

See the example_with_targets for details on usage, or use the following guide to convert an existing Rust-based function.

Updating an existing function to using shopify_function 2.0.0 and higher

If you are using a version less than 1.0.0, you should update to version 1.1.1 as outlined below before following these steps.

1. Update to the latest Shopify CLI version.

2. Install the wasm32-unknown-unknown build target using rustup target:

   rustup target add wasm32-unknown-unknown
   

3. Update your build command and path in the [extensions.build] section of your shopify.extension.toml to use wasm32-unknown-unknown instead of wasm32-wasip1. Replace RUST-PACKAGE-NAME with the name from your Cargo.toml:

   [extensions.build]
   command = "cargo build --target=wasm32-unknown-unknown --release"
   path = "target/wasm32-unknown-unknown/release/[RUST-PACKAGE-NAME].wasm"
   

4. Throughout all of your source files, update any references to eprintln! to use log! instead.

   #[shopify_function]
   fn run(input: schema::run::Input) -> Result<schema::FunctionRunResult> {
     log!("This will be logged");
     todo!();
   }
   

5. Throughout all of your source files, update any references to process::exit(1) to use process::abort() instead.

   #[shopify_function]
   fn run(input: schema::run::Input) -> Result<schema::FunctionRunResult> {
     log!("Please invoke a named export.");
     process::abort();
   }
   

Updating an existing function using a version of shopify_function below 1.0.0 to use version 1.0.0 and above

1. In main.rs, add imports for shopify_function.

   use shopify_function::prelude::*;
   use shopify_function::Result;
   

2. In main.rs, add type generation, right under your imports. Remove any references to the generate_types! macro. Replace ./input.graphql with the location of your input query file (e.g. src/run.graphql).

   #[typegen("./schema.graphql")]
   pub mod schema {
      #[query("./input.graphql")]
      pub mod input {}
   }
   

   If your Function has multiple targets each with their own input query, add a nested module for each. For example:

   #[typegen("./schema.graphql")]
   pub mod schema {
      #[query("src/target_a.graphql")]
      pub mod target_a {}
   
      #[query("src/target_b.graphql")]
      pub mod target_b {}
   }
   

3. In main.rs, ensure that you have a main function that returns an error indicating to invoke a named export:

   fn main() {
      eprintln!("Invoke a named import");
      std::process::exit(1);
   }
   

4. Throughout all of your source files, replace any references to #[shopify_function_target] with the shopify_function macro, and change its return type. Typically, this is located in a file with a name equal to the target, e.g. run.rs.

   #[shopify_function]
   fn run(input: schema::input::Input) -> Result<schema::FunctionRunResult> {
   

5. Update the types and fields utilized in the function to the new, auto-generated structs. For example:

   Old	New
   input::ResponseData	schema::input::Input
   input::InputDiscountNodeMetafield	schema::input::input::discount_node::Metafield
   input::InputDiscountNode	schema::input::input::DiscountNode
   output::FunctionRunResult	schema::FunctionRunResult
   output::DiscountApplicationStrategy::FIRST	schema::DiscountApplicationStrategy::First

   If referencing generated types from a file other than main.rs where they are defined, you'll need to import the schema. For example in run.rs you would need to add:

   use crate::schema;
   

Viewing the generated types

To preview the types generated by the typegen macro, use the cargo doc command.

cargo doc --open

You can also use the cargo-expand crate to view the generated source, or use the rust-analyzer VSCode extension to get IntelliSense for Rust and the generated types.

License MIT