diff --git a/apps/docs-app/docs/experimental/sfc/index.md b/apps/docs-app/docs/experimental/sfc/index.md new file mode 100644 index 000000000..398ccd666 --- /dev/null +++ b/apps/docs-app/docs/experimental/sfc/index.md @@ -0,0 +1,375 @@ +--- +sidebar_position: 1 +--- + +# Analog SFCs + +> **Note:** +> +> This file format and API is experimental, is a community-driven initiative, and is not an officially proposed change to Angular. Use it at your own risk. + +The `.analog` file extension denotes a new file format for Angular Single File Components (SFCs) that aims to simplify the authoring experience of Angular components. + +Together, it combines: + +- Colocated template, script, and style tags +- No decorators +- Performance-first defaults (`OnPush` change detection, no accesss to `ngDoCheck`, etc.) + +# Usage + +To use the Analog SFC format, you need to use the Analog Vite plugin or the [Analog Astro plugin](/docs/packages/astro-angular/overview) with an additional flag to enable its usage: + +```typescript +import { defineConfig } from 'vite'; +import analog from '@analogjs/vite-plugin-angular'; + +export default defineConfig({ + // ... + plugins: [ + analog({ + vite: { + // Required to use the Analog SFC format + experimental: { + supportAnalogFormat: true, + }, + }, + }), + ], +}); +``` + +## IDE Support + +To support syntax highlighting and other IDE functionality with `.analog` files, you need to install an extension to support the format for: + +- [WebStorm 2024.1+ or IDEA Ultimate 2024.1+](https://github.com/analogjs/idea-plugin) + +> [Support for VSCode is coming! Please see this issue for more details](https://github.com/volarjs/angular-language-tools/). + +## Additional Configuration + +If you are using `.analog` files outside a project's root you will need to specify all paths of `.analog` files using globs, like so: + +```typescript +export default defineConfig(({ mode }) => ({ + // ... + plugins: [ + analog({ + vite: { + experimental: { + supportAnalogFormat: { + include: ['/libs/shared/ui/**/*', '/libs/some-lib/ui/**/*'], + }, + }, + }, + }), + ], +})); +``` + +# Authoring an SFC + +Here's a demonstration of the Analog format building a simple counter: + +```html + + + + + +``` + +See the [defineMetadata](#metadata) section for adding additional component metadata. + +# Metadata + +While class decorators are used to add metadata to a component or directive in the traditional Angular authoring methods, they're replaced in the Analog format with the `defineMetadata` global function: + +```typescript +defineMetadata({ + host: { class: 'block articles-toggle' }, +}); +``` + +This supports all of the decorator properties of `@Component` or `@Directive` with a few exceptions. + +## Disallowed Metadata Properties + +The following properties are not allowed on the metadata fields: + +- `template`: Use the SFC `