ionic

ionic Best Practices

Ionic Framework enables powerful cross-platform applications. Adhering to these guidelines ensures your codebase is robust, performant, and aligned with modern web development standards.

1. Code Organization and Structure

Adopt a consistent, component-centric file structure for clarity and maintainability.

1.1 One Component Per Directory

Each Ionic component (or Stencil component it wraps) must reside in its own directory, co-locating all related files.

❌ BAD: Scattered files

// components/my-button.tsx
// components/my-button.css
// components/my-card.tsx
// components/my-card.css

✅ GOOD: Component-per-directory

├── components
│   ├── ion-button
│   │   ├── ion-button.css
│   │   └── ion-button.tsx
│   └── ion-card
│       ├── ion-card.css
│       └── ion-card.tsx

1.2 Naming Conventions

Use descriptive, noun-based names for components, prefixed for uniqueness.

• HTML Tag: Use a unique, brand-specific prefix (e.g., ion-). Names should be nouns.
• TS Class: No prefix for the ES6 class name, as classes are scoped.

❌ BAD: Verb-based or un-prefixed tags

// my-animating.tsx
@Component({ tag: 'animating-component' })
export class AnimatingComponent {}

✅ GOOD: Noun-based, prefixed tags

// ion-animation.tsx
@Component({ tag: 'ion-animation' })
export class Animation {}

1.3 Component File Structure (Newspaper Metaphor)

Organize component class members logically, from high-level summaries to detailed implementations.

@Component({
  tag: 'ion-example',
  styleUrls: {
    ios: 'ion-example.ios.css',
    md: 'ion-example.md.css',
  },
})
export class IonExample {
  /** 1. Internal Properties (not exposed) */
  private internalValue: number = 0;

  /** 2. Reference to host HTML element */
  @Element() el!: HTMLElement;

  /** 3. State() variables (internal reactive state) */
  @State() isActive: boolean = false;

  /** 4. Public Property API (@Prop()) with JSDocs */
  /**
   * The text to display on the button.
   */
  @Prop() text: string = '';

  /**
   * If `true`, the button is disabled.
   */
  @Prop() disabled: boolean = false;

  /** 5. Prop lifecycle events (@Watch()) */
  @Watch('disabled')
  disabledChanged(newValue: boolean, oldValue: boolean) {
    console.log(`Disabled changed from ${oldValue} to ${newValue}`);
  }

  /** 6. Events section (@Event()) with JSDocs */
  /**
   * Emitted when the button is clicked.
   */
  @Event() ionClick!: EventEmitter<void>;

  /** 7. Component lifecycle events (ordered by natural call order) */
  connectedCallback() { /* ... */ }
  disconnectedCallback() { /* ... */ }
  componentWillLoad() { /* ... */ }
  componentDidLoad() { /* ... */ }
  componentWillRender() { /* ... */ }
  componentDidRender() { /* ... */ }

  /** 8. Listeners (@Listen()) */
  @Listen('click', { target: 'document' })
  onClick(event: Event) {
    if (event.target === this.el) {
      this.ionClick.emit();
    }
  }

  /** 9. Public Methods (@Method()) with JSDocs */
  /**
   * Focuses the button.
   */
  @Method()
  async setFocus() {
    this.el.focus();
  }

  /** 10. Private Methods (internal logic) */
  private updateInternalState() {
    this.internalValue++;
  }

  /** 11. Render function (JSX/TSX) */
  render() {
    return (
      <button disabled={this.disabled} onClick={() => this.ionClick.emit()}>
        {this.text}
      </button>
    );
  }
}