Skip to main content
Use this guide when one Grasshopper definition is becoming too large, or when multiple people or tools need to work on different stages of the same pipeline. It shows how to treat Speckle models as the interfaces between Grasshopper modules. For users who already publish and load data with Speckle in Grasshopper.
Before you start: You need the Speckle Grasshopper connector installed and basic familiarity with the Publish and Load nodes. If you are new to Speckle in Grasshopper, see the Grasshopper connector guide first.
Connectors from 2026.8 or earlier cannot load versions published by the 2026.9 Publish node. Everyone who loads a module’s output needs the 2026.9 connector. See Upgrade to 2026.9.
Grasshopper Speckle ribbon with the Publish and Load nodes

​
When to componentise a Grasshopper definition

When to use: Your definition is complex enough that separate files or owners make sense.
1

Identify natural module boundaries

Look for stages that already exist in your definition such as “base geometry generation”, “analysis setup”, “visualisation prep”, or “documentation”. Each of these is a candidate module.
2

Decide what each module owns

For each stage, decide what it is responsible for producing (e.g. cleaned room solids with metadata, analysis meshes, layout curves). These become the public outputs that downstream modules rely on.
3

Check who needs to work on each stage

If different people or teams own different stages (e.g. design vs analysis), componentising makes collaboration clearer. Even for one person, modules help separate experiments from stable logic.
Outcome: A list of modules with clear responsibilities that you can split into separate Grasshopper files.

​
Design the Speckle interfaces between modules

When to use: Before creating separate Grasshopper files.
1

Create a Speckle project and models for the workflow

In Speckle, create a project that will hold all models for this workflow. For each module, plan one or more models (e.g. 01_base-geometry, 02_analysis-input, 03_visualisation). A typical pipeline: one module publishes base geometry to a model; a second consumes it and publishes analysis input; a third consumes that and produces documentation or exports.
2

Define the contract for each module output

For each module, decide what data will be sent to Speckle. Be explicit about object types, required properties, naming, and units. Treat this as a contract: downstream modules should be able to rely on it remaining stable.
3

Choose how you will version data

Decide whether downstream modules should always use the latest version of a model or pin to specific versions for repeatable runs. For automated or production workflows, prefer pinned versions to avoid surprises.
The flow is: upstream Grasshopper file → Publish → Speckle model → Load → downstream Grasshopper file. Outcome: A simple map of which models carry data between modules, and what each of them contains.

​
Build an upstream module that publishes to Speckle

When to use: Creating the first module in the chain that produces data for others.
1

Start a Grasshopper file for the module

Copy only the part of your existing definition that belongs to this module into a new Grasshopper file. Keep its inputs focused on what this module actually needs to run.
2

Add a Publish node at the output

Place a Publish node from the Speckle Grasshopper connector at the point where you want to expose data. Connect the geometry and data you identified in your contract as its input.
Grasshopper definition with a Publish node publishing to Speckle
3

Configure account, server, project, and model

Set up the Publish node with the correct Speckle account, server, project, and model name (e.g. 01_base-geometry). Use clear, stable names that reflect the module’s role.
4

Shape data for downstream consumers

Before publishing, clean and structure the data: group elements logically, wrap geometry in Speckle Object nodes so names and properties sit on the object, ensure important properties are present and named consistently, and avoid publishing unused or experimental data. Aim for a tidy structure that downstream modules do not need to reinterpret.
5

Publish and verify in Speckle

Run the definition and publish. Open the project in Speckle, inspect the model, and confirm that objects, properties, and naming match your intended contract.
Outcome: A standalone Grasshopper module that publishes a well‑defined Speckle model for others to consume.

​
Build downstream modules that consume Speckle models

When to use: Creating modules that depend on data from earlier stages.
1

Start a new Grasshopper file per downstream module

Create a separate Grasshopper definition for each downstream stage (e.g. analysis, reporting, documentation). Keep inputs and outputs explicit so the file is easy to reason about.
2

Add Load nodes for upstream models

Place one or more Load nodes and point them at the upstream models (e.g. 01_base-geometry). If stability matters, pin the node to a specific version.
Grasshopper definition with a Load node loading from Speckle
3

Adapt loaded data to local needs

Convert loaded objects into the types, structures, and units this module uses internally. This is also where you can add module‑specific properties or perform filtering based on tags or parameters.
4

Optionally publish this module's outputs

If another module will consume this stage, add a Publish node at your module’s output and repeat the configuration and shaping steps. Choose a model that clearly names this stage (e.g. 02_analysis-input).
5

Test modules together

Run the upstream module to publish fresh data, then run the downstream module and confirm that the Load nodes pick up the expected objects. Fix any contract mismatches before adding more complexity.
Outcome: One or more downstream modules that reliably consume Speckle models from upstream and can themselves publish clean outputs.

​
Coordinate between people and tools

When to use: Multiple people, machines, or tools share responsibility for the pipeline.
1

Assign clear ownership per module

Decide who owns each module and where its Grasshopper file lives (e.g. version‑controlled repository). Owners are responsible for keeping the Speckle contracts stable and documented.
2

Document contracts alongside the files

For each module, record which Speckle project and models it reads and writes, and what each output contains. A short README next to the Grasshopper file is often enough.
3

Agree on change management

Establish how upstream changes are communicated. For example, require a brief note whenever object structure or key properties change, and schedule time for downstream owners to adapt.
4

Run modules on appropriate machines

Let heavy geometry or analysis modules run on powerful workstations or dedicated machines, while lighter reporting or visualisation modules can run elsewhere. Speckle models carry the data between them.
Outcome: Teams can work on different stages without sharing one large Grasshopper file, and changes propagate via well‑defined Speckle models.

​
Common patterns and pitfalls

  • Pattern: Linear pipeline
    • One module publishes base geometry; another prepares analysis input; a third produces documentation or exports. Each stage reads from and writes to a dedicated Speckle model.
  • Pattern: Branching workflows
    • A single upstream model feeds multiple downstream modules (e.g. daylight analysis, cost estimation, visualisation). All downstream Load nodes point at the same upstream model or version.
  • Pitfall: Publishing everything
    • Publishing the entire Grasshopper state makes downstream modules brittle and hard to understand. Instead, publish only what is needed and keep contracts small.
  • Pitfall: Unannounced schema changes
    • Changing property names or structures without coordination breaks downstream modules. Treat contracts as shared APIs and change them deliberately.

​
FAQ

Use as many modules as you need to keep responsibilities clear and files manageable. A common pattern is 2–4 modules (e.g. base geometry, analysis prep, reporting, and exports) rather than a large number of very small ones.
Yes. Any number of Grasshopper files or other tools can load from the same project and model. This is a good way to centralise base geometry and fan out into specialised workflows.
For exploratory work, using the latest version keeps things simple. For repeatable analysis or production runs, pin Load nodes to specific versions so results can be reproduced and compared reliably.
Update the upstream module’s contract to include the additional properties or objects, then add them to the Publish node. Coordinate the change with all downstream owners so they can take advantage of the new data without breaking existing logic.
First, inspect the upstream Speckle model in the web viewer to confirm that objects and properties look as expected. Then check the Load node configuration and any conversion logic in the downstream file. Work from the interface inwards rather than from deep inside the definition.
Yes. Any tool with a Speckle connector or SDK can read from and write to the same models. For example, analysis tools, dashboards, or scripts can consume the outputs of Grasshopper modules or publish new stages in the pipeline.
Models can grow large, but very heavy payloads will affect publish and load times and downstream performance. If models become unwieldy, consider splitting them by discipline, zone, or purpose so modules only consume what they need.
No. Componentised workflows work with manual publishing and loading. Automate becomes useful when you want these modules to run automatically on triggers, but it is not required for the pattern itself.

​
See also

Last modified on October 19, 2026