Introducing the .ng format in Analog [CLOSED]

[brandonroberts]

This opens the discussion around #823. The goal is to get early feedback about the feature in its experimental phase.

This introduces experimental support for a .ng format for components, directives, and pipes. Initial work done by @nartc and @brandonroberts, with early discussions also contributed by @joshuamorony.

Why

• Forward-looking for new component authoring format
• Simpler mental model for component authoring
• Similar to other frameworks that's not JSX-based
• Doesn't change authoring services
• Works with existing concepts and components
• Works more seamlessly with new functions, lifecycle hooks

Notes

• This is enabled with an experimental flag through the Vite config.
• Components/directives can be used immediately in the template after imported.
• Uses Angular's experimental-local compilation mode.
• SSR is not currently supported.
• Inputs/Outputs are not currently supported.
• Deferrable Views are not currently supported.
• defineComponentMetadata , defineDirectiveMetadata, and definePipeMetadata are used to define metadata for components, directives, and pipes.

Revisions

2024/01/02

• Support for custom pipes have been removed in favor of using computed
• defineComponentMetadata , defineDirectiveMetadata have been consolidated into defineMetadata. A component requires a <template> where a directive does not.

2024/01/03

• Pipe metadata removed
• exposes property added to metadata for exposing globals, enums to the template
• onDestroy hook added to go along with onInit
• Object Destructure and Array Destructure are supported.
  • Destructuring reactive values will NOT work

  const data = signal({ firstName: 'chau', lastName: 'tran' });
  // if `data` updates, `firstName` and `lastName` will NOT update
  const { firstName, lastName } = data();

2024/01/04

• let variables are supported by utilizing getters via Object.defineProperties

2024/01/11

• Inputs are now supported via Angular 17.1 Signal Inputs
• Outputs are now supported via calling new EventEmitter() directly
  • No alias for Outputs for now.

2024/01/25

• Support for .ng files is removed

Concepts

/// <reference types="vitest" />

import { defineConfig } from 'vite';
import analog from '@analogjs/platform';

// https://vitejs.dev/config/
export default defineConfig(({ mode }) => ({
  // ... other config
  plugins: [
    analog({
      ssr: false,
      vite: {
        experimental: {
          dangerouslySupportNgFormat: true
        }
      },
    }),
  ],
}));

Component

hello.ng

<template>
  <p>hello works!</p>
</template>

app.component.ng

<script lang="ts">
  import { inject, signal, effect, computed } from '@angular/core';
  import { JsonPipe } from '@angular/common';
  import { HttpClient } from '@angular/common/http';
  import { delay } from 'rxjs';

  import Hello from './hello.ng';
  import Highlight from './highlight.ng';
  import Doubled from './doubled.ng';

  defineMetadata({
    selector: 'app-root',
    imports: [JsonPipe],
  });

  const title = 'Analog';

  const http = inject(HttpClient);

  const counter = signal(1);
  const doubled = computed(() => counter() * 2);
  const todo = signal(null);

  const increment = () => {
    counter.update((value) => value + 1);
  };

  function decrement() {
    counter.update((value) => value - 1);
  }

  effect(() => {
    console.log('counter changed', counter());
  });

  onInit(() => {
    console.log('App init');
    http
      .get('https://jsonplaceholder.typicode.com/todos/1')
      .pipe(delay(2000))
      .subscribe((data) => {
        todo.set(data);
        console.log('data', data);
      });
  });
</script>

<template>
  @if (counter() > 2) {
    <Hello />
  }

  <p>Counter: {{ counter() }}</p>
  <p highlight>Doubled: {{ doubled() }}</p>
  <p>Doubled with Pipe: {{ counter() | doubled }}</p>
  <button (click)="increment()">increment</button>
  <button (click)="decrement()">decrement</button>

  @if (todo(); as todo) {
  <pre>{{todo | json }}</pre>
  } @else {
  <p>Loading todo...</p>
  }
</template>

<style>
  p {
    color: red;
  }

  button {
    background: blue;
    color: white;
    padding: 1rem 0.5rem;
    border-radius: 0.5rem;
  }
</style>

Pipe (No longer included)

doubled.ng

<script lang="ts">
  definePipeMetadata({
    name: 'doubled',
  });

  function transform(value: number) {
    return value * 2;
  }
</script>

Directive

highlight.ng

<script lang="ts">
  import { afterNextRender, ElementRef, inject } from '@angular/core';

  defineMetadata({
    selector: 'p[highlight]',
  });

  const elementRef = inject<ElementRef<HTMLElement>>(ElementRef);

  afterNextRender(() => {
    elementRef.nativeElement.style.backgroundColor = 'yellow';
  });
</script>

Lifecycle Hooks

An onInit lifecycle hook can be added for init logic.

<script>
  onInit(() => {
    console.log('App init');
    http
      .get('https://jsonplaceholder.typicode.com/todos/1')
      .pipe(delay(2000))
      .subscribe((data) => {
        console.log('data', data);
      });
  });
</script>

<template>
  <p>Component Init</p>
</template>

An onDestroy lifecycle hook can be added for teardown logic.

<script lang="ts">
  onDestroy(() => {
    console.log('hello destroyed');
  });
</script>

<template>
  <p>Component Destroy</p>
</template>

Alternatively, DestroyRef can also be used for teardown logic instead:

<script lang="ts">
  import { inject, DestroyRef } from '@angular/core';

  inject(DestroyRef).onDestroy(() => {
    console.log('hello destroyed');
  });
</script>

Sample App

https://github.com/brandonroberts/analog-ng

[joshuamorony]

Pretty sure I don't need to reiterate how much I like/want this - thank you Brandon and Chau for spearheading this!

Just a couple of initial thoughts/nits:

• Not sure if it makes it easier to implement, but my preference would be for no <template> tag
• I think it feels somewhat unintuitive that adding init/destroy behaviour is handled differently - perhaps also add an onDestroy hook to keep this consistent?
• Perhaps something like ngPipe() and ngDirective() (or maybe just defineDirective) for the metadata instead of defineDirectiveMetadata- not sure what would be best but defineDirectiveMetadata feels a bit verbose

I also wonder whether the .ng file makes sense for directives/pipes? Perhaps rather than:

doubled.ng

We would stick with something like doubled.pipe.ts but instead of using decorators/classes it would be created entirely within the function, e.g:

doubled.pipe.ts

definePipe({
  name: 'doubled',
  transform: (value: number) => {
    return value * 2
  }
})

Of course, this is coming purely from the perspective of how I would ideally want this to work without considering how much this complicates the actual implementation

[brandonroberts]

I like both ideas. If using a computed is going to be preferred vs pipes, we should direct people to those.

[brandonroberts]

I also prefer defineMetadata vs metadata as its too concise IMO, but not strongly.

[ajitzero]

getting rid of Pipes

This is very reasonable for almost every pipe, but I'm unsure how to approach the async pipe? signal.set(..) inside a manual subscribe()? What am I overlooking?

Edit: nvm, we can probably use toSignal.

[nartc]

@ajitzero you're overlooking toSignal

[nartc]

Feedbacks are implemented here: #826

[tayambamwanza]

Just here to bikeshed that I'm pro <template> tag 👀 but otherwise I'll definitely be experimenting with this.

[brandonroberts]

We landed on using a <template> because it's more straightforward to parse, but I can see the value in either approach. It also helps separate a component from a directive more clearly.

[lukaszpiotrluczak]

I could agree with reasoning. I only wonder if this is really a problem to parse when we don't have <template> tag?

If parser have default context of template then when <script>, <style> or any other support tag is used it will just change context to properly parse that part and then go back.

It will even allow us to add multiple <script>'s in component, or maybe even give them a scope and use it to inline event handler.

[nartc]

It's not impossible. We can always iterate on the syntax at this moment. Feel free to include any kind of snippets that resonate with your ideas and we can discuss further.

[Jordan-Hall]

<script lang="ts">
  import {
    DestroyRef,
    inject,
    input,
    EventEmitter,
    effect,
    ViewChild,
    ElementRef,
    afterNextRender,
  } from '@angular/core';

  import { myFunc } from './export-stuff.ng';

  defineMetadata({
    queries: {
      divElement: new ViewChild('divElement'),
    },
    exposes: [myFunc],
  });

  let divElement: ElementRef<HTMLDivElement>;

  afterNextRender(() => {
    console.log('the Div', divElement);
  });

  const { foo: aliasFoo = 'tran', ...rest } = { foo: 'chau' };
  const [a, b, , c = 5, ...restArray] = [1, 2, 3];

  const text = input('');

  effect(() => {
    console.log('text changed', text());
  });

  const clicked = new EventEmitter<MouseEvent>();

  inject(DestroyRef).onDestroy(() => {
    console.log('hello destroyed');
  });
</script>

  <h1>Hello.ng again</h1>
  <p>{{ a }}</p>
  <p>{{ b }}</p>
  <p>{{ c }}</p>
  <p>{{ aliasFoo }}</p>
  <p>Text from input: {{ text() }}</p>
  <button (click)="clicked.emit($event)">Emit The Click</button>
  <div #divElement>my div</div>
  <p>From imported function: {{ myFunc() }}</p>


<style>
  :host {
    display: block;
    padding: 1rem;
    border: 1px dashed red;
    border-radius: 0.5rem;
  }
</style>

I was looking at it for langauge service. If you take the start and end loc for style and script. Anything else is the HTML

[joshvanallen]

Just a quick flyby question...is specifying the script language truly needed? Is that a requirement for Vite or something else?

[brandonroberts]

Its required as it provides better Intellisense within an IDE

[Jordan-Hall]

@brandonroberts what IDE are you using/plugin. When im using it with TS im getting no extra help it doesnt understand typings :/

[nartc]

@Jordan-Hall VSCode with Volar (Vue Language Service (Volar)) extension and set the .ng files to .vue files.

[Jordan-Hall]

Thank you I assumed it would be like that. Is anyone working on a actual angular volar language service to support .ng

[goetzrobin]

I love this! This is incredible work!

This has me dreaming of supporting MDX rendering with something like this:

<script>
import Hello from './hello.ng';
</script>

<markdown>
  # Hello World
 <Hello />
</markdown>

Do you guys think this would be possible?

[brandonroberts]

Definitely have considered this also, but want to get the foundation down first. I floated this idea also.

<template lang="md">
</template>

[lukaszpiotrluczak]

Hmm... this situation defends idea to use <template> approach.

Will it require much work to add possibility to easily extend with other formats than html, md?

[nartc]

Another option is a different file extension that follows Markdown syntax rather than HTML (so no script tags and co.)

[goetzrobin]

I do see the value of seeing what type of content is in the file based on the file ending...

But I also love how good this looks:

<script lang="ts">
import Hello from './hello.ng';
</script>

<template lang="md">
  # Hello World
 <Hello />
</template>

But no matter what the second this is supported I'll be all over it! Happy to help make it a reality, too, if there is any way I can help contribute!

[Jordan-Hall]

I like to add saying ng is a analog framework/authoring. I think using lang on all three tags would be useful and beneficial. The example by @goetzrobin seems like a good way to go about this and keeps learning curve small. Better than mutiple file types where it can get people confused.

[luishcastroc]

I love it, I'm pro and I would love to help on this if needed, one question do we need to have a .ng for directives and pipes as well? That looks a little odd but other than that this looks fantastic

[brandonroberts]

We've already scoped it down to just components and directives, and will remove .ng pipes.

[ducin]

What are the potential possibilities of making it a pre-processor so that standard Angular apps can make use of it as well? Have you identified any critical obstacles, other than lack of supporting features such as deferrable views, inputs, outputs etc?

[brandonroberts]

I'll say upfront that this won't be possible with standard Angular apps because there is no direct access to the underlying Angular compilation process and this is by design in Angular. Its not a limitation of Angular, but an agreed-upon constraint by the Angular team. We are not sidestepping that process either, as we're still going through the Angular compilation process in the end.

These will only be available in Analog for the foreseeable future, unless Angular introduces a different authoring format, which they said they are not doing at the moment.

There aren't any critical obstacles at the moment, but additional features like signal inputs will be added when they are added to Angular upstream.

[Yberion]

Hello, it is going to be only available as SFC?

[brandonroberts]

Unless there is some compelling reason otherwise, yes. If you want to split up your component into separate files, you can still use a class component.

[nartc]

I thought I saw a notification about Generics Component. That is definitely something I had on my mind but I didn't have a concrete idea as to how to implement it. So I'm open-mind about it

[brandonroberts]

I saw it also, maybe I misunderstood the context of the question.

[krivanek06]

I like it very much. For lifecycle hooks I think we would need some eslint support. You can accidentally make a mistake my writing inInit() instead of onInit() ... maybe somehow incorporate not necessarily implementing interfaces, but somehow use them. For example the ControlValueAccessor is quite a common interface to implement

[nartc]

Thank you for the feedback.

1. A LSP support might be better than a linter. That is something we have in mind, but will see if the progress of .ng warrants the time put into creating a LSP
2. Good point regarding ControlValueAccessor. We'll need to figure out something. Feel free to shoot us ideas if you come up with something too.

[Jordan-Hall]

If you need to implement something wouldn't it be better to use class for it without having to define the metadata? Alternatively you could do something like this when lang=ts

<script lang="ts" extends="" implement=""> I think doing it on the script tag better than in defineMetadata for example. Plus you can easily abstract it from the tags.

[brandonroberts]

Yea, I don't think we should be extending the script tag that way. Seems too far off from its intended usage. If you need to do class-based things, use a class component. Let's not build a pseudo-class language in the script tag itself.

[Jordan-Hall]

I agree with, i dont like the idea of building into script tag. I guess the only question is around export. I think personally dont use .ng file for anything that needs to extend or implement.

[nartc]

re:ControlValueAccessor https://ngxtension.netlify.app/utilities/forms/control-value-accessor/ someone actually submits a utility to implement ControlValueAccessor without implements ControlValueAccessor

[KevTale]

That looks promising! GG guys 👏

Here's a couple of questions:

1. Are all variables in <script> exported in <template>? How can I prevent the template to access some variables?
2. How does routing works for .ng files as it was previsously handled by the class being exported by default? Can we expect maybe something like some.route.ng and some.component.ng? I like the fact that you can visually determine what is the purpose of a file just by looking at its name.
3. Can I place the <script> tag in the bottom of the file rather than at the very top?

[nartc]

1. Currently, there is no syntax available to determine which variables can be accessed on the template. While we technically have the option to use export const ... to only expose certain variables to the template, it may not be worthwhile.
2. I'll let @brandonroberts answer this
3. Yes, you can place the script tag at the bottom.

[brandonroberts]

1. Agreed. I would reserve export for inputs/outputs, but we may be able to target those based on the function being used input() or output() in the future. We'd have to come up some conventions to keep variables out of the template scope.
2. We could support the same naming convention as .page.ng instead of page.ts to support the file-based routing. We do use some conventions based on the file names for "auto-imports" though.

[louiss0]

I'd like to be able to have multiple templates in one file.
Can that be a thing. Svelte has it.

[louiss0]

I'm talking about ng-template and ng container. Without having to import anything.

<template>
<ng-container *ngTemplateOutlet="greet"></ng-container>
</template>

<ng-template #greet>
Hello World  
</ng-template>

[nartc]

I can make NgTemplateOutlet auto-imported. For this case, you'd still want the ng-template to be inside of the template tag

[louiss0]

Please try to find a way to not make this the case the code would look extremely disgusting and it would be difficult to sort from the main template.

[nartc]

the tag acts as a boundary only. Literally everything inside it is brought over to the "template" property in the component's metadata.

[louiss0]

Okay

[marcus-sa]

Shouldn't inject(DestroyRef).onDestroy just be onDestroy without having to import or inject anything?

[nartc]

It is now. But I guess Brandon would have to cut another release to include that change.

[brandonroberts]

The latest beta is published 0.2.30-beta.3 and includes the updates

[vneogi199]

Not sure if I missed it, but I would to see variables/enums directly accessible in the template without creating an instance of them in the script section.

<script lang="ts">
  import {myVar, ColorEnum} from 'another-one.ng';
</script>


<template>
Variable is: {{myVar}}

Is variable blue: {{myVar === ColorEnum.BLUE}}
</template>

[nartc]

Currently, we don't analyze the template to check thr bindings so for things like imported variables (lile an emum) or global symbols (like Math), you'd want to use exposes to expose them on the template (again, @brandonroberts might need to cut a new version 😅)

<script lang="ts">
defineMetadata({
  exposes: [Math, MyEnum]
})
</script>

[brandonroberts]

The latest beta is published 0.2.30-beta.3 and includes the updates

[vneogi199]

I dont know if its technically possible to do something like:

templateContext = {...currentTemplateContext, windowGlobals, importsFromScriptTag, exportedVariablesFromScriptTag}

this way these will be available within template context.

[nartc]

It is technically possible to do anything that is within the JS syntax 😅

[xocomil]

Wow! I unplug for a few weeks and you guys drop something this huge! This looks amazing and I am excited to see where your ideas lead. I'm curious about how feasible functional components become with the helper functions. For example, would the following be possible?

  const component1 = createComponent(withMetadata({imports: [ signalStore, myPipe]}), withTemplate(`<h1>{{myStore.value()}}</h1>`);
  const component2 = createComponent(...);

There is some "magic" I'm glossing over here, but I'm more curious if you think the idea is feasible given the research you have done with the compiler.

I love this idea. I think it will make Angular more accessible.

[nartc]

If you are able to provide a full example, it'd help a bit more. Also, does this have anything to do with .ng files or just a suggestion at yet a different author format?

[xocomil]

Mainly curiosity on my part. I'm experimenting with some ideas right now. I was hoping to steal some of yours... 🤣

[marcus-sa]

I don't know if it's useful to you, but you can actually patch the Angular compiler to support custom transformers.
I've done something similar that you can see here and here.

[brandonroberts]

Thanks. We're not trying to maintain a fork of the Angular compiler though

[joshvanallen]

keep toying away with this and thinking about a few things:

• for the logic that's outside of a lifecycle function, where is that code placed? Is it in the constructor or placed on the class itself (I'm assuming at the end of the day this gets translated into a class)?
• NgModule support? Granted we are two major versions since standalone was properly released, there's still libs out there that rely on it. more of a clarifying question/setting expectations for everyone

[nartc]

1. Top-level expressions (i.e: effect(() => {})) are placed in the "class" constructor (you can take a look at the test snapshot for ng.ts)
2. NgModule would still work.

   <script lang="ts">
   defineMetadata({
     imports: [CommonModule]
   })
   </script>

[MitchSmoot]

I remember seeing Brandon's politely worded tweet earlier about lack of functional components "pushing angular into niche markets". My initial reaction was: why change it if it isn't broken? But after seeing this implementation, even after sharing some initial concerns in a response to Joshua's tweet, I'm really warming up to this. Plus, we get to flex on the tech blogosphere which is always a good thing.

I think it is a fantastic addition for angular devs who know what they are doing. But I have not gotten to the point of thinking it should be recommended to new developers. Having multiple, interchangeable, ways of doing a thing makes it harder to learn. All of the tutorials, examples, docs are in the original syntax, and I don't think it would be an enjoyable experience for a new dev who doesn't understand the workings and flow of the framework to have to try and write in this new syntax when all their online resources are written the other way. BUT if we can create really good documentation that include more substantive examples, I think we can alleviate that concern. I would be happy to help contribute to such documentation.

I see myself using both authoring forms initially, old way for pages, new way for components on pages, or small components. Could switch wholly to the new format if it feels nice in practice.
The use cases I am most looking forward to:

• three.js or angular-three components
• Astro x Analog applications

This authoring syntax seems like a home run for Astro+Analog projects. I don't think I need to say more.
Components like those built with angular-three that already prefer single-file format are a natural fit, and I cant wait to use them in my current project. Will there need to be a special angular-three integration or will it work with this out of the box? @nartc I would love to hear your perspective on this. I'm almost at the point where I would donate my kidney to try this out with angular-three 2.0, haha.

[nartc]

angular-three should work out of the box for this. We might be able to do something extra to .ng file if that file needs CUSTOM_ELEMENTS_SCHEMA or something but they should just work out of the box.

Now that you remind me, I want to build angular-three with the new format as well but building the library is different 😅.

[ajitzero]

Can we skip defining the selector for components?

It would still be needed for directives, but components are already being renamed with import Hello from './hello.ng'; as <Hello /> instead of <app-hello />. If needed internally, we could use the file name (maybe?) to generate the component name.

I would love to be able to skip the wrapper element à la React Fragments, but that might be beyond the scope here.

Thoughts?

[nartc]

Yes, by default the file name will be used as the selector

hello.ng -> selector: 'hello,HELLO,Hello',
another-one.ng -> selector: 'another-one,AnotherOne,ANOTHER_ONE'

you can omit selector for components.

[nartc]

re:Fragment
Yes, this is beyond the scope. We don't do anything different in terms of rendering. That will have to come from Angular upstream

[Jordan-Hall]

Currently the styles are added to the template in the meta. Should the styles be moved to the styles in the meta to support multiple <style> tags or is it only 1 thats allowed?

[brandonroberts]

We tried putting them the styles instead of combining them in the template but they weren't being applied correctly. What's the use case to need more than one?

[Jordan-Hall]

My thinking was because Angular allows multiple. Do you mind if I take a look at the styles and combining, Looking through the code means you wouldn't be able to do SCSS for example right? Unless processing it inside of analog. If it going to be process inside of analog wouldn't you need a lang attribute to styles?

[Jordan-Hall]

Another reason for asking is to block it from being allowed

[Jordan-Hall]

Proposal drop then .ng and rename it. This allows angular to use the file name in future without and clashes especially if this comes out of experimental for analog

[brandonroberts]

Good idea. We were already considering this prior to yesterday

[Jordan-Hall]

I thought you would. Could be cheeky and do something like .ngx but would love to see this more oauh as analog with angular di and rendering system. This changing file ext be helpful and free up for angular in future