Bubbling cache tag metadata when rendering nodes in preprocess functions is difficult

Be that as it may, it seems the majority of FE developers tend to stick to preprocess functions and templates. What alternative route would you recommend? I haven't seen any simpler way of rendering one node inside another yet in D8 :-/

Related? #2660002: Allow explicit bubbling of cacheability metadata inside Twig template (when accessing data from instead of rendering render arrays)

@Berdir - here's a high-level overview of what we're doing, in code:

/**
 * Implements hook_preprocess_hook().
 *
 * We need to look up related component data for this product for its display.
 */
function beagov_theme_preprocess_node(&$variables) {
  $view_builder = \Drupal::entityTypeManager()->getViewBuilder('node');
  $node = $variables['node'];
  $product_id = $node->id();

  // Get the related component.
  $query = \Drupal::entityQuery('node')
    ->condition('status', 1)
    ->condition('type', 'component')
    ->condition('field_product', $product_id)
    ->sort('created', 'DESC')
    ->range(0, 1);
  $result = $query->execute();
  $component = Node::loadMultiple($result);

  // Get a renderable teaser view.
  $variables['component_teaser'] = $view_builder->viewMultiple($component, 'teaser');
}

Then, inside node--product.html.twig, we have:

<div class="component">
  {{ component_teaser }}
</div>
<div class="product">
  {{ content }}
</div>

Not exactly the code we're using, but you get the gist.

The only thing I can think of is adding new children, that makes sense, you need to add the node_list or a more specific cache tag, or invalidate the correspending parent cache tag when saving a children, but that's by design and not related to preprocess.

Thinking about it with my backend dev hat on, this does make sense. But it's (a) not obvious why it doesn't work out of the box (like it did in Drupal < 8, when all the page cache was cleared when you saved a new node...), and (b) difficult to find an example of how to clear the parent when the child is saved/updated.

I mean, in one sense this is just a documentation issue. But it's not the first time I've run into a theme-related cache tag issue where google searches are fruitless and the examples in the Cache/Render API documentation are not specific enough to quickly find a solution. I can only imagine someone who's more of a front end developer/site builder and doesn't dig deeper into the question will end up disabling the dynamic page cache entirely because of these kinds of issues...

For the site in question, we'll likely find and clear the parent node's cache tag manually, but it took too much time for us to go from 'why isn't this working like we thought it would?' to 'we may have a working solution'. I want to reduce that time for others in our situation in the future!

In the interest of assisting others who will likely hit this issue in the future, here's how we fixed it on our site (so we can use the method in #2848158-8: Bubbling cache tag metadata when rendering nodes in preprocess functions is difficult to print a teaser display of a child content type in a parent content type page that the child references:

/**
 * Implements hook_node_insert().
 *
 * NOTE: You should likely also do this in hook_node_update()!
 */
function mymodule_node_insert(EntityInterface $entity) {
  if ($entity->bundle() == 'mynodetype') {
    if (!empty($entity->field_node_reference->getValue())) {
      $reference_value = $entity->field_node_reference->getValue();
      _mymodule_invalidate_node_cache_tags($reference_value);
    }
  }
}

/**
 * Invalidate a node by an entity reference field value.
 *
 * @param array $entity_reference_value
 *   An entity reference field value array.
 */
function _mymodule_invalidate_node_cache_tags($entity_reference_value) {
  $node_id = array_shift($entity_reference_value);
  $node = Node::load($node_id['target_id']);
  $tags = $node->getCacheTagsToInvalidate();
  Cache::invalidateTags($tags);
}

This seems to work okay in our instance. Any way to make it more efficient? It would be nice if there were a way in core to just say "invalidate cache tags for this node" and pass it an ID...