Add API Usage docs to @glimmer/ssr

[izelnakri]

This documentation might be helpful for others trying to figure out how this works, it will show up in the npm after a new release.

I still haven't figured out how to embed components inside component scopes, still trying to figure out how.

The code below doesn't work for template imports/component composition(fixed in other comments below):

import { setComponentTemplate } from '@glimmer/core';
import component from '@glimmer/component';
import { renderToString } from '@glimmer/ssr';

import { templateFactory } from '@glimmer/opcode-compiler';
import { precompile } from '@glimmer/compiler';

let GlimmerComponent = component.default;

class AnotherComponent extends GlimmerComponent {}
setComponentTemplate(
  templateFactory(JSON.parse(
    precompile(`<h5>This is another component</h5>`, { strictMode: true }))
  ),
  AnotherComponent
);

class PageComponent extends GlimmerComponent {}
setComponentTemplate(
  templateFactory(JSON.parse(
    precompile(`
      {{#let "hello" "world" as |hello world|}}<p>{{hello}} {{world}}</p>{{/let}}
      <AnotherComponent />
    `, {
      strictMode: true,
      scope: () => {
        return { AnotherComponent };
      }
    }))
  ),
  PageComponent
);

console.log(await renderToString(PageComponent, {
  owner: {
    services: {
    },
  },
}));

[izelnakri]

I was able to embed components with the following hack:

import { setComponentTemplate } from '@glimmer/core';
import component from '@glimmer/component';
import { renderToString } from '@glimmer/ssr';

import { templateFactory } from '@glimmer/opcode-compiler';
import { precompileJSON } from '@glimmer/compiler';

let GlimmerComponent = component.default;
let templateId = 0;

// NOTE: this function is needed instead of @glimmer/core precompile?
function createTemplate(
  templateSource,
  options,
  scopeValues = {}
) {
  options.locals = options.locals ?? Object.keys(scopeValues ?? {});
  let [block, usedLocals] = precompileJSON(templateSource, options);
  let reifiedScopeValues = usedLocals.map((key) => scopeValues[key]);

  let templateBlock = {
    id: String(templateId++),
    block: JSON.stringify(block),
    moduleName: options.meta?.moduleName ?? '(unknown template module)',
    scope: reifiedScopeValues.length > 0 ? () => reifiedScopeValues : null,
    isStrictMode: options.strictMode ?? false,
  };

  return templateFactory(templateBlock);
}

class AnotherComponent extends GlimmerComponent {}
setComponentTemplate(
  createTemplate(`<h5>This is another component</h5>`, { strictMode: true }),
  AnotherComponent
);

class PageComponent extends GlimmerComponent {}
setComponentTemplate(
  createTemplate(`
    {{#let "hello" "world" as |hello world|}}<p>{{hello}} {{world}}</p>{{/let}}
    <AnotherComponent />
  `, {
    strictMode: true,
  }, { AnotherComponent: AnotherComponent }),
  PageComponent
);

// prints the rendered html of PageComponent including AnotherComponent
console.log(await renderToString(PageComponent, {
  owner: {
    services: {
    },
  },
}));

[izelnakri]

ok everything works with @glimmer/ssr, happy to see its near final!:

import { setComponentTemplate, getOwner, helperCapabilities, setHelperManager } from '@glimmer/core';
import component from '@glimmer/component';
import { renderToString } from '@glimmer/ssr';

import { templateFactory } from '@glimmer/opcode-compiler';
import { artifacts } from '@glimmer/program';
import { precompile, precompileJSON } from '@glimmer/compiler';

// FRAMEWORK SETUP:
// =================
let GlimmerComponent = component.default;
let templateId = 0;

function createTemplate(
  templateSource,
  options,
  scopeValues = {}
) {
  options.locals = options.locals ?? Object.keys(scopeValues ?? {});
  let [block, usedLocals] = precompileJSON(templateSource, options);
  let reifiedScopeValues = usedLocals.map((key) => scopeValues[key]);

  let templateBlock = {
    id: String(templateId++),
    block: JSON.stringify(block),
    moduleName: options.meta?.moduleName ?? '(unknown template module)',
    scope: reifiedScopeValues.length > 0 ? () => reifiedScopeValues : null,
    isStrictMode: options.strictMode ?? false,
  };

  return templateFactory(templateBlock);
}

class HelperWithServicesManager {
  capabilities = helperCapabilities('3.23', {
    hasValue: true,
  });

  constructor(owner) {
    this.owner = owner;
  }

  createHelper(fn, args) {
    return { fn, args, services: this.owner.services };
  }

  getValue(instance) {
    const { args, services } = instance;
    return instance.fn(args.positional, args.named, services);
  }
}

const HelperWithServicesManagerFactory = (owner) => new HelperWithServicesManager(owner);

function helper(fn) {
  setHelperManager(HelperWithServicesManagerFactory, fn);
  return fn;
}
// ==============================

// APPLICATION CODE:
// ==============================
class AnotherComponent extends GlimmerComponent {
  get localeService() {
    return getOwner(this).services.locale;
  }

  get currentLocale() {
    return getOwner(this).services.locale.currentLocale;
  }
}
setComponentTemplate(
  createTemplate(`
    <h5>This is another component</h5>
    <p>Current locale is {{this.currentLocale}}, description: {{this.localeService.description}}</p>
  `, { strictMode: true }),
  AnotherComponent
);

const myHelper = helper(function ([name], { greeting }) {
  return `Helper: ${greeting} ${name}`;
});

const isUSA = helper(function (_args, _hash, services) {
  const localeService = services.locale;

  return localeService.currentLocale === 'en_US';
});

class PageComponent extends GlimmerComponent {}
setComponentTemplate(
  createTemplate(`
    {{#let "hello" "world" as |hello world|}}<p>{{hello}} {{world}}</p>{{/let}}
    {{myHelper "foo" greeting="Hello"}}
    <p>Current locale: {{this.currentLocale}}</p>
    {{#if (isUSA)}}
      <p>Component is in a US locale</p>
    {{else}}
      <p>Component is not in a US locale</p>
    {{/if}}
    <AnotherComponent />
  `, { strictMode: true }, { AnotherComponent, myHelper, isUSA }
  ),
  PageComponent
);

class LocaleService {
  currentLocale = "es";

  constructor(currentLocale) {
    this.currentLocale = currentLocale;
  }

  get locales() {
    if (this.currentLocale === "en") {
      return {
        "button.save": "Save model",
        "button.delete": "Delete model",
        "profile.about.description": "This is description",
      };
    }

    return {
      "button.save": "Guardar modelo",
      "button.delete": "Eliminar modelo",
      "profile.about.description": "Esta es un description",
    };
  }

  get description() {
    return this.locales['profile.about.description'];
  }

  t(key) {
    return this.locales[this.currentLocale][key];
  }
}
// ============================

// SERVER-SIDE RENDERING: (outputs everything correctly)
// ============================
console.log(await renderToString(PageComponent, {
  owner: {
    services: {
      locale: new LocaleService('en_US')
    }
  },
}));
// ============================

[rwjblue]

Awesome, thanks!