> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Widget Files and Code

## Article: Widget Files and Code

## Article Link: https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/site-extensions/blocks-site-widgets/widget-files-and-code.md

## Article Content:

# Files and Code for Blocks Site Widgets

<blockquote classname="warning">

**Deprecated**

The Wix CLI for Apps is deprecated and no longer receives updates or new features. New projects should use the unified [Wix CLI](https://dev.wix.com/docs/wix-cli/guides/about-the-wix-cli.md). [Determine which CLI your project uses](https://dev.wix.com/docs/wix-cli/guides/development/determine-which-cli-your-project-uses.md).

</blockquote>

<blockquote class="important">

**Important:** The Blocks-CLI integration only works with the [Wix CLI for Apps](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/about-the-wix-cli-for-apps.md). The new [Wix CLI](https://dev.wix.com/docs/wix-cli/guides/about-the-wix-cli.md), which is the recommended tool for new app projects, doesn’t support this integration.

</blockquote>

When you [add a Blocks site widget extension](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/site-extensions/blocks-site-widgets/add-a-blocks-site-widget-extension-in-the-cli.md) to your CLI project, the CLI generates the following directory structure in your project repo:

```tsx
.
└── <your-app-name>/
    └── src/
        └── site/
            └── widgets/
                └── blocks/
                    └── <your-widget-name>
                        ├── api.ts
                        ├── widget.json
                        └── widget.ts
```


In the your site widget folder, the following files are created:

+ An [`api.ts`](#apits) file that contains the declarations for your [Widget API](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/widget-api/about-the-widget-api.md) properties, events, and functions. These are exposed when your widget is installed on a site (in the Wix Editors) or when it's added inside another widget.
+ A `widget.json` file that contains the ID of your widget. Do not modify this file.
+ A [`widget.ts`](#widgetts) file that contains the logic for your widget. Here you implement and use the properties, events, and functions that you declared in `api.ts`.

If you add [panels](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/editor-experience-panels/about-panels-in-blocks.md) to your widget in the Blocks editor and sync to the CLI, a `panels` directory is created inside your widget’s directory. `panels` contains subdirectories for each panel you added in Blocks. For more information about the panels code files, see [Files and Code for Blocks Site Widget Panels](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/site-extensions/blocks-site-widgets/panel-files-and-code.md)

## api.ts

When you [add a Blocks site widget extension in the CLI](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/site-extensions/blocks-site-widgets/add-a-blocks-site-widget-extension-in-the-cli.md), an `api.ts` file is generated for the extension. This file contains the declarations for your [Widget API](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/widget-api/about-the-widget-api.md) properties, events, and functions.

When you add a new blocks site widget to your project, you'll see the following code in `api.ts`:

```tsx
import { defineAPI, WidgetPropertyType } from '@wix/blocks';

export default defineAPI({
  props: {
    name: {
      type: WidgetPropertyType.STRING,
    },
  },
  events: { load: {} },
  methods: {
    myPublicFunction: {},
  },
});
```

You can implement and use these properties, events, and functions in your [`widget.ts`](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/site-extensions/blocks-site-widgets/widget-files-and-code.md) file. They are exposed when your widget is installed on a site (in the Wix Editors) or when it's added inside another widget. 

### Properties

Declare widget properties as key-value pairs within the `props` object. 

Each value must be an object that specifies a `type` and may optionally specify a `defaultValue` for initializing the property.

Property types can only be strings.

#### Example

```tsx
props: {
  productId: {
    type: WidgetPropertyType.STRING,
    defaultValue: '02c08513-f267-4073-bac5-0f8c2dfa8b76'
  },
  productInfo: {
    type: WidgetPropertyType.STRING
  }
}
```

When a widget is added to a site, your app (and users) can interact with your widget properties using [`$widget`](https://dev.wix.com/docs/velo/velo-only-apis/$widget/introduction.md).

> **Note:** The Blocks-CLI integration currently doesn’t support custom type properties.

### Methods

Declare methods you want your widget to expose within the `methods` object. You must return these methods from `defineWidget()` in your [`widget.ts`](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/site-extensions/blocks-site-widgets/widget-files-and-code.md) file.

### Events

Declare events you want your widget to trigger within the `events` object. You can trigger these events in `defineWidget()` in your [`widget.ts`](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/site-extensions/blocks-site-widgets/widget-files-and-code.md) file.

## widget.ts

When you [add a Blocks site widget extension in the CLI](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/site-extensions/blocks-site-widgets/add-a-blocks-site-widget-extension-in-the-cli.md), a `widget.ts` file is generated for the extension. This file contains the code for your site widget. 

When the `widget.ts` file is generated, it looks like this:

```tsx
import { defineWidget } from '@wix/blocks';

export default defineWidget(<your-widget-id>, ($w, $widget) => {
  $w.onReady(() => {
    // Initialize your widget here. If your widget has properties, this is a good place to read their values.
    console.log('Widget is ready');
  });

  $widget.onPropsChanged((oldProps, newProps) => {
    // If your widget has properties, onPropsChanged is where you should handle changes to their values.
    console.log('Widget props changed', {
      oldProps,
      newProps,
    });
  });

  return {
    // If your app exposes a function in the api.ts file, make sure to return it here.
    myPublicFunction() { }
  };
});

```

### defineWidget()

`defineWidget()` accepts a function that will execute when your widget is added to a site. This function accepts the following namespaces as parameters, allowing you to work with them in your code:

#### $w

[`$w`](https://dev.wix.com/docs/velo/velo-only-apis/$w/introduction.md) contains everything you need in order to work with your widget's components. It allows you to select elements in your widget and interact with them. Each element type exposes properties and functions that you use to enhance the functionality of your widget. 

##### $w.onReady()

[`$w.onReady()`](https://dev.wix.com/docs/velo/velo-only-apis/$w/on-ready.md) is called when all widget elements have finished loading.

Place your widget initialization logic inside the `$w.onReady` function.


#### $widget

[`$widget`](https://www.wix.com/velo/reference/$widget) contains functionality for working with your Blocks widget's API from within the widget code. It includes:
[properties](https://www.wix.com/velo/reference/$widget/props) for storing values associated with the widget.
A [handler function](https://dev.wix.com/docs/velo/velo-only-apis/$widget/on-props-changed.md) that runs when those properties change.
A function to [fire events](https://www.wix.com/velo/reference/$widget/fireevent) from your widget.

Properties and events must be defined in your [`api.ts`](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/site-extensions/blocks-site-widgets/widget-files-and-code.md) file.

For more information, see [About the Widget API in Blocks](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/widget-api/about-the-widget-api.md)

##### $widget.onPropsChanged()

`$widget.onPropsChanged()` is called whenever one of your widget’s properties is changed, taking the old and new properties as parameters. Add logic to this function to respond to these changes.

#### return{}

If you want your widget to expose any functions, specify them in the returned object. You define these functions in your widget’s [`api.ts`](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/site-extensions/blocks-site-widgets/widget-files-and-code.md) file.

#### Wix Javascript SDK

Use the [Wix Javascript SDK](https://dev.wix.com/docs/sdk.md) to access and manage Wix business solutions.

For example:

```tsx
import { products } from "@wix/stores";

async function useSDK () {
const result = await products.getProduct('12234'); 
console.log(result); 
}
```