# Installation

## Starter

The easiest way to use Concorde is by using the Concorde starter.  
The following command creates a new Vite project in TypeScript mode with Tailwind and an example component to get started.

<sonic-code language="shell">
  <template>
npx @supersoniks/create-concorde-ts-starter "project_name"
  </template>
</sonic-code>

## Brand New Vite Project


For a more manual configuration, you can refer to the following sections. <br/>
However, the Tailwind configuration is not mentioned at the moment.


### Creating the Project

<sonic-code language="shell">
  <template>
# Pure JavaScript project
yarn create vite --template vanilla-js
# TypeScript project
# (it is recommended to use this approach, which installs Lit separately if needed, via "yarn add lit")
yarn create vite --template vanilla-ts
# TypeScript + Lit project
# (creating new web components, for example, to extend the fetch or subscriber mixins)
yarn create vite --template lit-ts
  </template>
</sonic-code>

Using Lit with TypeScript requires the following configuration in the "compilerOptions" section of the `tsconfig.json` file:

<sonic-code language="json">
  <template>
"experimentalDecorators": true,
"useDefineForClassFields": false
  </template>
</sonic-code>

### Installing Concorde

Navigate to the project folder created and perform the installation:

<sonic-code language="shell">
  <template>
yarn add @supersoniks/concorde
  </template>
</sonic-code>

### Development / Build

<sonic-code language="shell">
  <template>
# Development (you can add `--host` after the command chain in package.json's dev script instead of typing it each time as shown below)
yarn dev --host
# Build
yarn build
  </template>
</sonic-code>

## Shortcut Imports

Shortcut imports work by default in JavaScript, but in TypeScript, they are activated by choice as they inject data into *tsconfig.json*. Here is the command:

<sonic-code language="shell">
  <template>
npx concorde enable-short-paths
  </template>
</sonic-code>

Shortcut imports replace the actual paths with aliases as follows:

* `@supersoniks/concorde/core/components/functional_or_ui/component/component` becomes `@supersoniks/concorde/functional_or_ui/component`
* `@supersoniks/concorde/core/mixins_or_utils/class_name` becomes `@supersoniks/concorde/mixins_or_utils/class_name`

The original paths remain accessible. Shortcut imports are used for the examples later in this documentation.

## Usage

### Simple Integration in HTML

Import needed component in `main.ts` or wherever you want to use it:

<sonic-code language="typescript">
  <template>
import "@supersoniks/concorde/ui/button";
  </template>
</sonic-code>

Then in the render function ofyour component or in the HTML of the web page that includes the compiled JS, use the component as follows:

<sonic-code>
  <template>
<sonic-button variant="outline">My button</sonic-button>
  </template>
</sonic-code>

### Using a Mixin to Create a New Lit Component

For example, create a file `my-element.ts` at the root:

<sonic-code language="typescript">
  <template>
import { html, LitElement } from "lit";
import { customElement, property } from "lit/decorators.js";
import Fetcher from "@supersoniks/concorde/mixins/Fetcher";
import Subscriber from "@supersoniks/concorde/mixins/Subscriber";

@customElement("my-element")
export class SonicComponent extends Fetcher(Subscriber(LitElement)) {
  @property() email = "";
  @property() first_name = "";
  @property() last_name = "";

  render() {
    return html`<div>
      ${this.first_name} ${this.last_name} : ${this.email}
    </div>`;
  }
}
  </template>
</sonic-code>

Import component `main.ts` or `main.js` or any other component that uses it to be compiled

<sonic-code language="typescript">
  <template>
import "./my-element";
  </template>
</sonic-code>

In the HTML of a JS or TS component or in the HTML of the web page containing the compiled JS:

<sonic-code language="html">
  <template>
<my-element serviceURL="https://reqres.in" dataProvider="api/users/2" key="data"></my-element>
  </template>
</sonic-code>