Graph CLI Improvements

Graph CLI is a great piece of software that has served its purpose successfully all this time.

As early adopters, from Protofire we were spectators of the evolution of this tool throughout the versions. We have even collaborated by reporting issues or suggested improvements that were quickly addressed.

However, it has not received any significant updates lately. We believe this tool still hides a potential not yet sufficiently exploited. In addition, we think the codebase could somehow be modernized to unlock new features.

In particular, we identify a series of aspects to improve the developer experience building subgraphs. We want to share some of those ideas:

  • Upgrading AssemblyScript. The current codebase is pegged to an ancient version of AS (). There are many new releases after that including numerous bug fixes and new features. For example, in the version of AS that the CLI uses you cannot convert a string to lowercase or uppercase or use Array.flat() to flatten a particular array (so far you have to write your own little tested and error-prone routines). Neither can you use numeric separators or enjoy a spec-compliant version of parseInt() just to name a few more improvements. Upgrading to the latest version would be possible to enjoy all those improvements and make upgrading easier in the future since the AS project left the prototype phase and now publishes regular semantic versions of the standalone compiler on npm.
  • Allow importing schema files from another package. This feature will enable reusing schema files from external libraries or other subgraphs; that means third-party helper libraries or toolkits will be able to distribute well-tested pieces of schema and reuse entities and patterns across the subgraphs. We believe reusing battle-tested code in addition to unit testing would definitely encourage high-quality subgraph and remove the code smell currently suffering from some large subgraphs. According to our reviews, this could be fully implemented on the CLI side without the need for graph-node changes by integrating some GraphQL tools to merge/stitching the schema during code generation.
  • Subgraph templating. Sometimes a subgraph developer needs to support more than one network for the same subgraph or support a few versions of a set of smart contracts in the same network. Currently, there is a workaround to achieve that using an external templating engine, but we think multiple network deployments deserves to be a built-in feature since it is a more common use case than it seems.
  • Modularize deployment strategies preparing CLI to deploy to hosted service or to mainnet or testnet The Graph Network conveniently.
  • Subgraph manifest improvements. Particularly, in our opinion still, there is room to improve on ABIs management. Improvements on that side could be having a particular generic section on the manifest to define ABIs in order to avoid duplicating them per data source.
  • Looks like CLI code structure needs to be updated to support many L1 networks in the future aside from Ethereum. Would be great to prepare the codebase for that moment.
  • Adding new commands:
    • Adding a validate command to be consumed by CI serves as a linter. This is reusing the current manifest and schema validation module to be called manually.
    • Adding a query command to send a query to the deployed subgraph and show results properly directly on the shell.
    • etc.

These are some of our thoughts and ideas to take Graph CLI to the next level.