{"id":13880619,"url":"https://github.com/Shopify/syrup","last_synced_at":"2025-07-16T17:30:48.363Z","repository":{"id":40401686,"uuid":"238968371","full_name":"Shopify/syrup","owner":"Shopify","description":"A type-safe GraphQL model generator for Kotlin, Swift, and TypeScript.","archived":false,"fork":false,"pushed_at":"2025-06-06T17:25:38.000Z","size":56334,"stargazers_count":111,"open_issues_count":14,"forks_count":9,"subscribers_count":248,"default_branch":"main","last_synced_at":"2025-07-10T18:31:08.162Z","etag":null,"topics":["code-generation","graphql","kotlin","swift","typescript"],"latest_commit_sha":null,"homepage":"https://shopify.github.io/syrup/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Shopify.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-07T16:10:40.000Z","updated_at":"2025-06-06T17:25:02.000Z","dependencies_parsed_at":"2024-11-24T12:18:54.526Z","dependency_job_id":null,"html_url":"https://github.com/Shopify/syrup","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/Shopify/syrup","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shopify%2Fsyrup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shopify%2Fsyrup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shopify%2Fsyrup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shopify%2Fsyrup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Shopify","download_url":"https://codeload.github.com/Shopify/syrup/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shopify%2Fsyrup/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265527542,"owners_count":23782480,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-generation","graphql","kotlin","swift","typescript"],"created_at":"2024-08-06T08:03:18.141Z","updated_at":"2025-07-16T17:30:47.923Z","avatar_url":"https://github.com/Shopify.png","language":"Swift","funding_links":[],"categories":["Swift"],"sub_categories":[],"readme":"![GitHub Actions status](https://github.com/Shopify/syrup/workflows/Swift/badge.svg) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n# Syrup\n\nSyrup generates strongly-typed Swift and Kotlin models based on the GraphQL queries used in your app. It generates client-side types to represent the queries, mutations, and responses that your app relies on.\n\n## Running Syrup\nXcode 9 is required to build this application.\n\n### Running via Command Line:\nBuild the tool by running:\n```bash\n$ make\n```\n\nThis will create an executable for you located at `.build/debug/Syrup`\nTo run Syrup, simply run the executable from the command line with the required [command](https://github.com/shopify/syrup#commands) and [launch arguments](https://github.com/shopify/syrup#launch-arguments)\n\n### Running via Xcode:\nFirst, create your Xcode project:\n```bash\n$ make xcode\n```\n\nSelect the Syrup scheme (Product -\u003e Scheme -\u003e Syrup)\n\nAfter this, the project should successfully build. To get it to successfully run, you must supply the required [command](https://github.com/shopify/syrup#commands) and [launch arguments](https://github.com/shopify/syrup#launch-arguments) by editing the Syrup target's scheme (Product -\u003e Scheme -\u003e Edit Scheme) and providing them as \"Arguments passed on launch\" under the Arguments tab.\n\n### Commands\nSyrup supports the following commands. The launch arguments of each command are described in more detail under [launch arguments](https://github.com/shopify/syrup#launch-arguments).\n\n#### generate\nThis will generate the models representing your GraphQL operations as well as the necessary support files.\n\n```bash\n$ .build/debug/Syrup generate \u003cOperations Location\u003e \u003cModels Destination\u003e \u003cSupport Files Destination\u003e \u003cTemplate\u003e\n```\n\n#### generate-models\nThis will generate only the models representing your GraphQL operations.\n\n```bash\n$ .build/debug/Syrup generate-models \u003cOperations Location\u003e \u003cModels Destination\u003e \u003cTemplate\u003e\n```\n\n#### generate-support-files\nThis will generate only the support files representing your GraphQL operations.\n\n```bash\n$ .build/debug/Syrup generate-support-files \u003cSupport Files Destination\u003e \u003cTemplate\u003e\n```\n\n### Launch Arguments\nThis lists the possible arguments to Syrup. Note that not all launch arguments apply to every command.\n\n#### Applies to generate and generate-models commands\n- **Operations Location**: This provides the path to the folder containing all of your graphql operation definitions. These files are expected to have the .graphql suffix and should be valid graphql operations.\n- **Models Destination**: This provides the path to the folder where the generated code should be written to.\n\n#### Applies to generate and generate-support-files commands\n- **Support Files Destination**: This provides the path to the folder where the support files the generated code relies on should be written to. This is provided as a separate argument from the models destination in the case that your app has multiple frameworks using Syrup and you would like them to all share the same support files.\n\n#### Applies to all commands\n- **Template**: This provides the path to the [Templates](https://github.com/Shopify/Syrup/tree/main/Templates) folder that are included in the Syrup repository.\n- **`--project`**: The (optional) location of the [YAML file](https://github.com/shopify/syrup#project-file-format) that describes the project. By default, `.syrup.yml` in the current directory is used.\n- **`--schema`**: The (optional) location of the [YAML file](https://github.com/shopify/syrup#schema-file-format) that describes the schema. By default, `.syrup.yml` in the current directory is used.\n- **`--override-schema`**: An optional argument to override the location of the schema to be used. Can be either a file path or URL.\n\n### Project File Format\nThe project file provides schema and project specific information. This includes the location of the schema, custom scalar mappings, the module name, access level override, and a suffix that is appended to the generated files.\n\nThe Shopify project uses something similar to the following:\n```yaml\nmoduleName: MerchantApi\nfilenameSuffix: \"Next\"\nheader: |\n        // Syrup auto-generated file\n        import SomeFramework\nsupportFilesHeader: |\n        // Syrup auto-generated support file\naccessLevelOverride: \"internal\" # optional field\ngenerateSelections: true # optional field\n```\n\n**moduleName**: This is the namespace under which all generated models will be defined. For example, a module name of `GraphQLApi` will result in all models being defined as `GraphQLApi.ShopNameQuery`, `GraphQLApi.ShopNameResponse` etc.\n\n**header**: This is a block that will be written to the top of every generated model file. It can be used to include some comments as well as any import statements you need. For example, if your support files are written to a different module, you can import them from the header block here.\n\n**supportFilesHeader**: This is similar to the header above, but will be written to the generated support files instead of the generated models.\n\n**acccessLevelOverride**: This is an optional field which allows you to change the access level of the generated code from the default of public. The only other valid option for Swift is \"internal\".\n\n**generateSelections:**: This is an optional field which generates a data structure representing the selections of every operation. The default value of this is \"false\".\n\n### Schema File Format\nThe schema file provides schema specific information. This includes the location of the schema and custom scalar mappings.\n\nThe Shopify project uses something similar to the following:\n```yaml\nlocation: https://app.shopify.com/services/ping/graphql_schema\ncustomScalars:\n- graphType: DateTime\n  nativeType: Date\n- graphType: Money\n  nativeType: Money\n- graphType: URL\n  nativeType: URL\n- graphType: FormattedString\n  nativeType: String\n- graphType: UnsignedInt64\n  nativeType: UInt64\n  rawValueType: String\n```\n\n**customScalars**:\n  - graphType: The typename described in the GraphQL schema.\n  - nativeType: The native language type it will be translated/mapped to.\n  - rawValueType: The transport or intermediary type that is seen in GraphQL responses. A CustomScalarResolver is required in order to translate to/from the `graphType` to the `nativeType`.\n\n## GraphQL Operation Format\nSyrup requires that every graphql operation begins with either `query`, `mutation` or `fragment`, and that all operations and fragments have a name. This name maps to the name of the generated Query and Response objects.\nExample:\n```graphql\nquery ShopName {\n   shop {\n      name\n   }\n}\n```\n\n## Syrup Artifacts\nThe code generator will create the following types of files:\n### Enumerations\nThis will create a basic swift enumeration that maps to the string values of the corresponding GraphQL type. These enums will only be created if a query references a field of the enum type.\n\n### Input Objects\nThese represent the data passed in to mutations. They are fully mutable reference types that are generated if a query requires an argument of the input type.\n\n### Queries\nThese are structs that represent the queries that can be performed in the app. They contain properties for all of the arguments the query requires and can be serialized to the GraphQL format required for the network request.\n\n### Mutations\nThese are the same as queries, and simply differ by name.\n\n### Responses\nThese are immutable value types that represent the deserialized response from a query. They conform to swift’s Decodable protocol to facilitate automatic deserializing from JSON response to these strongly typed models.\n\n### Fragments\nGraphQL fragments are pieces of queries that can be shared across multiple queries. The code generator will create protocols representing each fragment and will ensure the response objects of all queries that reference a fragment conform to its corresponding protocol.\n\n### Scalar Resolver\nThe Custom Scalar Resolver file is created to handle any of the custom coded scalars defined in your project file. If your project file specifies no custom coded scalars, you can simply use the BaseCustomScalarResolver file as the `customScalarResolver` property of your module type.\n\n### Module File\nIn Swift, Syrup will generate all its models as an extension off of a base \"module type\". In practice, this is represented by an empty enum. All generated models will be namespaced under this module type, which will provide easier autocompletion and will avoid naming collisions with other types in your project. It also serves as the location where the custom JSONDecoder and JSONEncoder's must be provided. It is recommended that users of Syrup define an extension on the module type (in a separate file to avoid Syrup overwriting it) that provides values for the `customEncoder`, `customDecoder`, and the `customScalarResolver` properties. These properties are used in the serialization and deserialization of Syrup models, and your code will not compile without them.\n\n### Support Files\nSyrup generates a set of support files based on the GraphQL schema and the custom scalars provided in the project file.\n\n#### GraphApi.swift\nThe `GraphApi.swift` file contains the base type definitions that generated models rely on. It has definitions for the `GraphApiQuery` and `GraphApiResponse` protocols which serve as the base for every operation and response model.\n\n## Integration\n\n### Gradle\n\nThe [Shopify/syrup-gradle](https://github.com/shopify/syrup-gradle) plugin provides Gradle tasks for generating support files and models for multiple schemas.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FShopify%2Fsyrup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FShopify%2Fsyrup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FShopify%2Fsyrup/lists"}