{"id":16487313,"url":"https://github.com/nerdsupremacist/graphaello","last_synced_at":"2025-04-05T12:08:52.699Z","repository":{"id":39977988,"uuid":"242351920","full_name":"nerdsupremacist/Graphaello","owner":"nerdsupremacist","description":"A Tool for Writing Declarative, Type-Safe and Data-Driven Applications in SwiftUI using GraphQL","archived":false,"fork":false,"pushed_at":"2022-06-27T16:18:40.000Z","size":24245,"stargazers_count":493,"open_issues_count":18,"forks_count":18,"subscribers_count":4,"default_branch":"develop","last_synced_at":"2024-10-12T13:33:06.782Z","etag":null,"topics":["codegen","command-line-tool","data-driven","declarative","graphql","swift","swiftui","type-safety"],"latest_commit_sha":null,"homepage":"https://graphaello.dev","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/nerdsupremacist.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["nerdsupremacist"]}},"created_at":"2020-02-22T14:06:25.000Z","updated_at":"2024-08-07T09:46:37.000Z","dependencies_parsed_at":"2022-06-25T21:15:15.002Z","dependency_job_id":null,"html_url":"https://github.com/nerdsupremacist/Graphaello","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerdsupremacist%2FGraphaello","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerdsupremacist%2FGraphaello/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerdsupremacist%2FGraphaello/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerdsupremacist%2FGraphaello/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nerdsupremacist","download_url":"https://codeload.github.com/nerdsupremacist/Graphaello/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247332612,"owners_count":20921853,"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":["codegen","command-line-tool","data-driven","declarative","graphql","swift","swiftui","type-safety"],"created_at":"2024-10-11T13:33:39.532Z","updated_at":"2025-04-05T12:08:52.673Z","avatar_url":"https://github.com/nerdsupremacist.png","language":"Swift","funding_links":["https://github.com/sponsors/nerdsupremacist"],"categories":[],"sub_categories":[],"readme":"![Low Effort Graphaello Logo](logo.png)\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Swift-5.3-orange.svg\" /\u003e\n    \u003ca href=\"https://quintero.io/blog/Graphaello/\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/tutorial-brightgreen.svg?style=flat\" alt=\"Twitter: @nerdsupremacist\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://twitter.com/nerdsupremacist\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/twitter-@nerdsupremacist-blue.svg?style=flat\" alt=\"Twitter: @nerdsupremacist\" /\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n# Graphaello\n\nUse GraphQL directly from your SwiftUI Views.\nGraphaello is a Code Generation Command Line Tool that allows you to use property wrappers in your SwiftUI Views, to use data from GraphQL.\n\nThe main features of Graphaello are:\n\n- 🕓/❗️ Loading and Error State handling\n- 📝 Declarative\n- 🔐 Type-Safety\n- 🧰 Reusable Components\n- 📖 Paging Support\n- 🐦 Only write Swift (your Swift code is your GraphQL code) \n\nIf you're looking for something like this, but for other platforms, Graphaello is heavily inspired by [Relay](https://github.com/facebook/relay).\n\n## Examples\n\nCode snippets are cool, but how does this look in a real project? Here are some Example Apps that you can take a look at.\n\n| Countries        | Music      | CovidUI |\n| ------------- |-------------| ---------- |\n| ![](https://github.com/nerdsupremacist/graphaello-countries-example/blob/master/demo.gif?raw=true)      | ![](https://github.com/nerdsupremacist/graphaello-music-example/blob/master/demo.gif?raw=true) | ![](https://github.com/nerdsupremacist/CovidUI/blob/master/demo.gif?raw=true) |\n| Simple Hello World App that displays information about a lot of different countries | More complex App that uses Paging and a lot of reusable components | Integrationg Test, displaying data from my own GraphQL API: CovidQL\n| Uses [Countries API](https://countries.trevorblades.com)      | Uses [GraphBrains](https://github.com/exogen/graphbrainz)      | Uses [CovidQL](https://github.com/nerdsupremacist/CovidQL)\n| [Repo](https://github.com/nerdsupremacist/graphaello-countries-example) | [Repo](https://github.com/nerdsupremacist/graphaello-music-example)      | [Repo](https://github.com/nerdsupremacist/CovidUI)\n\n## Tutorial\nThis Readme is intended to document everything about Graphaello, from the CLI and API.\nHowever, for starting out that's not the best resource. I wrote a [tutorial](https://quintero.io/blog/Graphaello/) where I go into the benefits of Graphaello and how to build a simple App to browse movies with it. This post is intended even for people who are not familiar GraphQL at all. So if you're interested please do check it out [here](https://quintero.io/blog/Graphaello/).\n\n![](https://quintero.io/images/rest-smoking-data.gif)\n\n## TLDR?\n\nLet's cut the chase and go directly to our first example of a View using Graphaello:\n\n```swift\n// Define a Cell\nstruct CharacterCell: View {\n    // Use the GraphQL Property Wrapper\n    @GraphQL(StarWars.Person.name)\n    var name: String?\n\n    @GraphQL(StarWars.Person.homeworld.name)\n    var home: String?\n\n    var body: some View {\n        HStack {\n            name.map { Text($0).bold() }\n            Spacer()\n            home.map { Text($0) }\n        }\n    }\n}\n```\n\nThis code tells Graphaello to:\n- Generate a GraphQL [Fragment](https://graphql.org/learn/queries/#fragments): A reusable definition of the `Person` type, made especially for your View:\n\n```graphql\nfragment CharacterCell_Person on Person {\n    name\n    homeworld {\n        name\n    }\n}\n```\n\n- Create an initializer for your View using this type:\n\n```swift\nlet person: CharacterCell.Person = ...\nlet view = CharacterCell(person: person)\n```\n\n**And did I mention it's all type safe?!?!**\n\n```swift\n@GraphQL(StarWars.Person.name)\nvar name: String? // works\n\n@GraphQL(StarWars.Person.name)\nvar name: Bool // doesn't work\n```\n\n**AAAAaaaaand:** if it's a scalar then you don't even need to specify the type!!\n\n```swift\n\n@GraphQL(StarWars.Person.name)\nvar name // Swift knows it's a String?\n```\n\n## Installation\n\nPlease remember that Graphaello is in its early stages and is therefore not production ready. Use at your own caution. \n\n### Via Homebrew\n\nGraphaello can be installed via Homebrew:\n\n```\nbrew tap nerdsupremacist/tap\nbrew install graphaello\n```\n\n### From Source\n\nOr if you are one of those, you can install it directly from the source code. You do you!\n\n```\ngit clone https://github.com/nerdsupremacist/Graphaello.git\ncd Graphaello\nsudo make install \n```\n\n## Usage\n\nWe will cover how to use Graphaello from two sides. \n\n- What can you do in your code, \n- and how to you use the Command Line Tool:\n\n### Code\n\nAlmost all examples will refer to the Star Wars API: https://swapi-graphql.netlify.com\n\n#### Views\n\nYou very easily use information from a GraphQL API directly from your SwiftUI View:\n\nFor example this `CharacterCell` displays a single Cell with a Person's Name and Home World\n\n```swift\nstruct CharacterCell: View {\n    @GraphQL(StarWars.Person.name)\n    var name: String?\n\n    @GraphQL(StarWars.Person.homeworld.name)\n    var home: String?\n\n    var body: some View {\n        HStack {\n            name.map { Text($0).bold() }\n            Spacer()\n            home.map { Text($0) }\n        }\n    }\n}\n\n// Initializer is automatically created by Graphaello\nlet view = CharacterCell(person: person)\n```\n\n#### Composing Views\n\nIf your view has a sub view with it's own data, your view doesn't need to know the specifics of it, but only the fact that it needs to populate it:\n\n```swift\nstruct CharacterDetail: View {\n    @GraphQL(StarWars.Person._fragment)\n    var headerCell: CharacterCell.Person\n    \n    @GraphQL(StarWars.Person.eyes)\n    var eyes: String?\n\n    var body: some View {\n        VStack {\n           CharacterCell(person: headerCell)\n           eyes.map { Text($0) }\n        }\n    }\n}\n\nlet view = CharacterDetail(person: person)\n```\n\n#### Using Queries\n\nYou can access any query fields of the API directly: \n\n```swift\nstruct FilmView {\n  // .film refers to a field in the query\n  @GraphQL(StarWars.film.title)\n  var title: String?\n  \n  var body: String {\n    title.map { Text($0) }\n  }\n}\n\nlet client = ApolloClient(url: ...)\nlet api = StarWars(client: client)\n\nlet view = api.filmView(id: ...)\n```\n\n#### Using Mutations\n\nAll mutations can directly be used from `{API_NAME}.Mutation`. For this example we're using a TODO app since the Star Wars API doesn't support mutations:\n\n```swift\nstruct TodoCell: View {\n    // _nonNull() is equivalent to !\n    @GraphQL(Todos.Todo.id._nonNull())\n    var id: String\n\n    // _withDefault(FOO) is equivalent to ?? FOO\n    @GraphQL(Todos.Todo.title._withDefault(\"\"))\n    var title: String\n    \n    @GraphQL(Todos.Todo.completed._withDefault(false))\n    var completed: Bool\n\n    @GraphQL(Todos.Mutation.toggle.completed._withDefault(false))\n    var toggle: Toggle // Define a type name for your mutation\n\n    var body: some View {\n        HStack {\n            Text(title)\n\n            Spacer()\n            \n            Button(completed ? \"Mark as not done\" : \"Mark as done\") {\n              toggle.commit(id: self.id) { completed in \n                self.completed = completed\n              } \n            }\n\n            ActivityIndicator().animated(toggle.isLoading)\n        }\n    }\n}\n```\n\n#### Using Paging\n\nIf your API suppors Connections you can include paging in your App out of the box:\n\n```swift\nstruct CharacterList: View {\n    @GraphQL(StarWars.allPeople._nonNull())\n    var characters: Paging\u003cCharacterCell.Person\u003e\n\n    var body: some View {\n        List {\n            ForEach(characters.values) { character in \n                CharacterCell(person: character)\n            }\n            \n            characters.hasMore ? Button(\"Load More\") {\n              self.characters.loadMore()\n            }.disabled(characters.isLoading) : nil\n        }\n    }\n}\n```\n\nOr you can even use the Shipped `PagingView` and items will automatically load when you get near the end of the list:\n\n```swift\nstruct CharacterList: View {\n    @GraphQL(StarWars.allPeople._nonNull())\n    var characters: Paging\u003cCharacterCell.Person\u003e\n\n    var body: some View {\n        List {\n            PagingView(characters) { character in\n                CharacterCell(person: character)\n            }\n        }\n    }\n}\n```\n\n#### Handling arguments\n\nWhevener you use fields with arguments, those arguments are propagated to whoever uses your view. But you can also prefill them from the `@GraphQL` annotation. You can :\n\n- Use the default from the API (default behavior)\n- Force them to be filled by the caller\n- Hard code them\n- Override the default value\n\n**Default**\n\n```swift\nstruct FilmView {\n  @GraphQL(StarWars.film.title)\n  var title: String?\n  \n  var body: String {\n    title.map { Text($0) }\n  }\n}\n\n...\nlet first = api.filmView(id: ...)\nlet second = api.filmView() // uses the default from the API\n```\n\n**Force them**\n\n```swift\nstruct FilmView {\n  @GraphQL(StarWars.film(id: .argument).title)\n  var title: String?\n  \n  var body: String {\n    title.map { Text($0) }\n  }\n}\n\n...\nlet view = api.filmView(id: ...) // id is required\n```\n\n**Hardcode them**\n\n```swift\nstruct MyFavoriteFilmView {\n  @GraphQL(StarWars.film(id: .value(\"...\")).title)\n  var title: String?\n  \n  var body: String {\n    title.map { Text($0) }\n  }\n}\n\n...\nlet view = api.filmView() // id is not available as an argument\n```\n\n**Override the default**\n\n```swift\nstruct FilmView {\n  @GraphQL(StarWars.film(id: .argument(default: \"...\")).title)\n  var title: String?\n  \n  var body: String {\n    title.map { Text($0) }\n  }\n}\n\n...\nlet first = api.filmView(id: ...)\nlet second = api.filmView() // uses the default set by the View\n```\n\n#### Other operations\n\nThere are other operations available on Paths for Graphaello:\n\n- **_forEach(\\.{keyPath})** instead of getting an array of objects you can just get a specific value (will be transformed into an Array.map)\n- **_compactMap()** remove nils from an array (will be transformed into a `compactMap { $0 }`)\n- **_withDefault({y})** add a default value in case of nil (will be transformed into ` ?? y`)\n- **_nonNull()** force non null values (will be transformed into a `!`)\n- **_flatten** flatten an array of arrays (will be transformed into a `flatMap { $0 }`\n\n### Command Line Tool\n\nThe Graphaello Tool is pretty simple and only has three commands:\n\n- codegen: generates all the necessary code and injects it into your project\n- init: will install all dependencies and add a custom Graphaello buildphase (so that you don't need to use codegen manually)\n- add: will add a GraphQL API to your project\n\n#### Codegen\n\nWill generate all the swift code an insert it into your project.\n\n**Arguments:**\n\nProject: points to the project. If not provided will pick the first project in your current working directory\nApollo: Reference to which Apollo CLI it should use. Either \"binary\" (if you have installed it via npm) or \"derivedData\" (which will look into the build folder of your project. Only use this option from a build phase). If not provided it will default to the binary.\nSkip Formatting Flag: if your project is pretty large, formatting the generated code might take a lot of time. During prototyping you may want to skip formatting.\n\n#### Init\n\nInjects Graphaello into your project. This step is optional but recommended:\nWhen run it will:\n- add Apollo as a dependency (if it's not there already)\n- add a build phase to run codegen before every build (optional, not recommended for large projects)\n- run `codegen` (optional)\n\nYou can skip the optional steps using the flags:\n\n- skipBuildPhase\n- skipGencode\n\n### Add\n\nAdds an API to your project. Simply give the url to the GraphQL Endpoint and it will be added to your project.\n\n**Arguments:**\n\nAPI Name: you can change what the API will be called. If not Provided it will be a UpperCamelCase version of the host name\n\n\n## Contributions\nContributions are welcome and encouraged!\n\n## Related Work\n\n![](https://github.com/nerdsupremacist/GraphZahl/raw/develop/logo.png)\n\nGraphaello works best when coupled with [GraphZahl](https://github.com/nerdsupremacist/GraphZahl) on the Server Side. GraphZahl enables you to implement your GraphQL Server Declaratively in Swift with Zero Boilerplate.\n\n## Learn\nThis is currenlty a research project. More details about how it works, will be published later.\n\n## License\nGraphaello is available under the MIT license. See the LICENSE file for more info.\n\nThis project is being done under the supervision of the Chair for Applied Software Enginnering at the Technical University of Munich. The chair has everlasting rights to use and maintain this tool.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnerdsupremacist%2Fgraphaello","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnerdsupremacist%2Fgraphaello","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnerdsupremacist%2Fgraphaello/lists"}