Ciseco - Hydrogen Shopify's Headless Theme

https://nghiaxchis.gitbook.io/ciseco-hydrogen-shopifys-headless-theme/
Admin
Ciseco is a headless Shopify storefront theme built on Hydrogen and Oxygen that provides features...
Tokens:12,793
Snippets:87
Trust Score:10
Update:11 months ago
Show doc for...
Tokens:
Raw
### Run Ciseco Hydrogen Storefront Development Server

Source: https://nghiaxchis.gitbook.io/ciseco-hydrogen-shopifys-headless-theme/getting-started-1/step-1

Starts the local development server for the Ciseco Hydrogen storefront. After linking to Shopify and pulling environment variables, this command allows you to preview your storefront locally at http://localhost:3000.

```bash
npm run dev
```

--------------------------------

### Install Node.js Dependencies for Ciseco Hydrogen

Source: https://nghiaxchis.gitbook.io/ciseco-hydrogen-shopifys-headless-theme/getting-started-1/step-1

Installs the necessary Node.js packages for the Ciseco Hydrogen storefront. Requires Node.js v16.20+ and npm v8.19+. Ensure Git is initialized if encountering Git hooks errors before running.

```bash
npm install
```

--------------------------------

### Start ngrok for Local Development

Source: https://nghiaxchis.gitbook.io/ciseco-hydrogen-shopifys-headless-theme/ciseco-with-development-store/step-3

This command starts the ngrok tunneling service to create a public HTTPS domain for your local Hydrogen application. It requires an ngrok account and installation.

```bash
ngrok http --domain= 3000
```

--------------------------------

### Link Ciseco Hydrogen Project to Shopify Store

Source: https://nghiaxchis.gitbook.io/ciseco-hydrogen-shopifys-headless-theme/getting-started-1/step-1

Links the local Ciseco Hydrogen project to your Shopify store. This command initiates an interactive process to log in to your Shopify account and select or create a Hydrogen storefront.

```bash
npx shopify hydrogen link
```

--------------------------------

### Initialize Git Repository for Ciseco Hydrogen

Source: https://nghiaxchis.gitbook.io/ciseco-hydrogen-shopifys-headless-theme/getting-started-1/step-1

Initializes a Git repository in the project directory. This is a prerequisite step to resolve potential 'npm error command sh -c git config core.hooksPath hooks' errors during 'npm install'.

```bash
git init
```

--------------------------------

### Hydrogen Project Structure Example

Source: https://nghiaxchis.gitbook.io/ciseco-hydrogen-shopifys-headless-theme/hydrogen-and-oxygen-fundamentals

Illustrates the default directory layout for a Hydrogen Quickstart project. This structure organizes application files including components, routes, assets, and configuration files, following conventions established by the Remix framework.

```text
📂 hydrogen-quickstart/
├── 📁 app/
│   ├── 📁 assets/
│   ├── 📁 components/
│   ├── 📁 graphql/
│   ├── 📁 lib/
│   ├── 📁 routes/
│   ├── 📁 styles/
│   ├── entry.client.jsx
│   ├── entry.server.jsx
│   └── root.jsx
├── 📁 public/
├── CHANGELOG.md
├── README.md
├── customer-accountapi.generated.d.ts
├── env.d.ts
├── jsconfig.json
├── package.json
├── postcss.config.js
├── server.js
├── storefrontapi.generated.d.ts
├── tailwind.config.js
└── vite.config.js
```

--------------------------------

### Pull Shopify Environment Variables for Ciseco Hydrogen

Source: https://nghiaxchis.gitbook.io/ciseco-hydrogen-shopifys-headless-theme/getting-started-1/step-1

Pulls and updates the environment variables required for your Ciseco Hydrogen project from your linked Shopify store. It handles existing `.env` files by showing a diff or creates a new `.env` file if one doesn't exist.

```bash
npx shopify hydrogen env pull
```

--------------------------------

### Environment Variables Configuration (.env.local)

Source: https://nghiaxchis.gitbook.io/ciseco-hydrogen-shopifys-headless-theme/ciseco-with-development-store/step-2.-setup-environment-variables.

This bash snippet shows the required environment variables for a Shopify headless theme setup. These variables are crucial for configuring API access, store details, and user accounts. Ensure all placeholder values are replaced with your actual credentials.

```bash
PRIVATE_STOREFRONT_API_TOKEN="your_private_storefront_api" # e.g. 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
PUBLIC_STOREFRONT_API_TOKEN="your_public_storefront_api"
PUBLIC_STORE_DOMAIN="your_store_domain" # e.g. hydrogen-preview.myshopify.com
PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID="your_customer_account_api_client_id" # e.g. shp_ad7f793c-461f-4cec-bf1b-cxcxcxcxcxcx
PUBLIC_CUSTOMER_ACCOUNT_API_URL="https://shopify.com/xxxxxxxxxx" # e.g. https://shopify.com/68849271039
SESSION_SECRET="foobar"
PUBLIC_STOREFRONT_ID="foobar"
PUBLIC_CHECKOUT_DOMAIN=checkout.hydrogen.shop
PUBLIC_STORE_CDN_STATIC_URL="your_public_store_cnd_static_url" # e.g. https://cdn.shopify.com/s/files/1/1234/1234/1234/files/
PUBLIC_IMAGE_FORMAT_FOR_PRODUCT_OPTION='png'  # png/jpg/jpeg/webp/svg...
# OKENDO API (Optional)
PUBLIC_OKENDO_SUBSCRIBER_ID = "your_okendo_subscriber_id" # e.g. '0ddd53c2-21a9-455d-bf58-cxcxcxcxcxc'
```

--------------------------------

### Configure Content Security Policy in Hydrogen

Source: https://nghiaxchis.gitbook.io/ciseco-hydrogen-shopifys-headless-theme/ciseco-with-development-store/step-3

This Javascript snippet shows how to modify the content security policy in `/app/entry.server.tsx` to allow connections to your tunneled ngrok domain. Ensure the `connect-src` directive includes your ngrok domain.

```javascript
import {createContentSecurityPolicy} from '@shopify/hydrogen';
createContentSecurityPolicy({
  connectSrc: [
    // (ie. 'wss://<your-ngrok-domain>.app:*')
    'wss://<your-tunneled-host>:*',
  ],
});
```

--------------------------------

### Checkbox Component Example in JavaScript

Source: https://nghiaxchis.gitbook.io/ciseco-hydrogen-shopifys-headless-theme/component-structure

This JavaScript code defines a reusable Checkbox component. It includes props for 'name', 'label', and 'subLabel', and renders a checkbox input with associated labels. The component uses Tailwind CSS classes for styling.

```javascript
<div className="flex items-start">
  <div className="flex items-center h-5">
    <input
      id={name}
      name={name}
      type="checkbox"
      className="focus:ring-action-primary h-4 w-4 text-primary border-primary"
    />
  </div>
  {label && (
    <div className="ml-3 text-sm">
      <label
        htmlFor={name}
        className="text-paragraph-small text-black dark:text-white"
      >
        {label}
      </label>
      {subLabel && <p className="text-neutral-500">{subLabel}</p>}
    </div>
  )}
</div> 
```

--------------------------------

### Diagnosing Metaobject Import Errors in Shopify

Source: https://nghiaxchis.gitbook.io/ciseco-hydrogen-shopifys-headless-theme/cisecos-features/getting-the-problem-while-importing-demo-metaobjects-entries.

This snippet shows an example of an error message that indicates a metaobject already exists, preventing a successful import. The solution involves identifying the problematic metaobject from the error details and removing it from your Shopify admin before retrying the import.

```text
"errors": "Error when create Section Steps metaobject entries."
```

--------------------------------

### Default Localization Data for Shopify Theme

Source: https://nghiaxchis.gitbook.io/ciseco-hydrogen-shopifys-headless-theme/cisecos-features/internationalization-with-shopify-markets

This snippet shows the default localization data structure for the Ciseco Hydrogen Shopify Headless Theme. It includes settings for label, language, country, and currency. Customization of this data is required for specific projects. No external dependencies are noted.

```javascript
const countryData = {
  'XK': {
    label: 'Kosovo (EUR €)',
    language: 'EN',
    country: 'XK',
    currency: 'EUR',
  },
};

```

--------------------------------

### TypeScript: Define Available Countries for Localization

Source: https://nghiaxchis.gitbook.io/ciseco-hydrogen-shopifys-headless-theme/cisecos-features/internationalization-with-shopify-markets

This TypeScript code defines a `countries` object used for localizing a Shopify headless theme. It maps route paths to country-specific details like display label, language, country code, and currency. This structure helps manage different regional settings within the application.

```typescript
// ciseco-hydrogen-vite/app/data/countries.ts

import type {Localizations} from '~/lib/type';

export const countries: Localizations = {
  default: {
    label: 'United States (USD $)',
    language: 'EN',
    country: 'US',
    currency: 'USD',
  },
  '/en-ad': {
    label: 'Andorra (EUR €)',
    language: 'EN',
    country: 'AD',
    currency: 'EUR',
  },
  '/en-at': {
    label: 'Austria (EUR €)',
    language: 'EN',
    country: 'AT',
    currency: 'EUR',
  },
  '/en-au': {
    label: 'Australia (AUD $)',
    language: 'EN',
    country: 'AU',
    currency: 'AUD',
  },
  '/en-be': {
    label: 'Belgium (EUR €)',
    language: 'EN',
    country: 'BE',
    currency: 'EUR',
  },
  '/en-ca': {
    label: 'Canada (CAD $)',
    language: 'EN',
    country: 'CA',
    currency: 'CAD',
  },
  '/en-cn': {
    label: 'China (CNY ¥)',
    language: 'EN',
    country: 'CN',
    currency: 'CNY',
  },
  '/en-cy': {
    label: 'Cyprus (EUR €)',
    language: 'EN',
    country: 'CY',
    currency: 'EUR',
  },
  '/en-de': {
    label: 'Germany (EUR €)',
    language: 'EN',
    country: 'DE',
    currency: 'EUR',
  },
  '/en-ee': {
    label: 'Estonia (EUR €)',
    language: 'EN',
    country: 'EE',
    currency: 'EUR',
  },
  '/en-es': {
    label: 'Spain (EUR €)',
    language: 'EN',
    country: 'ES',
    currency: 'EUR',
  },
  '/en-fi': {
    label: 'Finland (EUR €)',
    language: 'EN',
    country: 'FI',
    currency: 'EUR',
  },
  '/en-fr': {
    label: 'France (EUR €)',
    language: 'EN',
    country: 'FR',
    currency: 'EUR',
  },
  '/en-gb': {
    label: 'United Kingdom (GBP £)',
    language: 'EN',
    country: 'GB',
    currency: 'GBP',
  },
  '/en-gr': {
    label: 'Greece (EUR €)',
    language: 'EN',
    country: 'GR',
    currency: 'EUR',
  },
  '/en-id': {
    label: 'Indonesia (IDR Rp)',
    language: 'EN',
    country: 'ID',
    currency: 'IDR',
  },
  '/en-ie': {
    label: 'Ireland (EUR €)',
    language: 'EN',
    country: 'IE',
    currency: 'EUR',
  },
  '/en-in': {
    label: 'India (INR ₹)',
    language: 'EN',
    country: 'IN',
    currency: 'INR',
  },
  '/en-it': {
    label: 'Italy (EUR €)',
    language: 'EN',
    country: 'IT',
    currency: 'EUR',
  },
  '/en-jp': {
    label: 'Japan (JPY ¥)',
    language: 'EN',
    country: 'JP',
    currency: 'JPY',
  },
  '/en-kr': {
    label: 'South Korea (KRW ₩)',
    language: 'EN',
    country: 'KR',
    currency: 'KRW',
  },
  '/en-lt': {
    label: 'Lithuania (EUR €)',
    language: 'EN',
    country: 'LT',
    currency: 'EUR',
  },
  '/en-lu': {
    label: 'Luxembourg (EUR €)',
    language: 'EN',
    country: 'LU',
    currency: 'EUR',
  },
  '/en-lv': {
    label: 'Latvia (EUR €)',
    language: 'EN',
    country: 'LV',
    currency: 'EUR',
  },
  '/en-mc': {
    label: 'Monaco (EUR €)',
    language: 'EN',
    country: 'MC',
    currency: 'EUR',
  },
  '/en-me': {
    label: 'Montenegro (EUR €)',
    language: 'EN',
    country: 'ME',
    currency: 'EUR',
  },
  '/en-mt': {
    label: 'Malta (EUR €)',
    language: 'EN',
    country: 'MT',
    currency: 'EUR',
  },
  '/en-nl': {
    label: 'Netherlands (EUR €)',
    language: 'EN',
    country: 'NL',
    currency: 'EUR',
  },
  '/en-nz': {
    label: 'New Zealand (NZD $)',
    language: 'EN',
    country: 'NZ',
    currency: 'NZD',
  },
  '/en-pt': {
    label: 'Portugal (EUR €)',
    language: 'EN',
    country: 'PT',
    currency: 'EUR',
  },
  '/en-sg': {
    label: 'Singapore (SGD $)',
    language: 'EN',
    country: 'SG',
    currency: 'SGD',
  },
  '/en-si': {
    label: 'Slovenia (EUR €)',
    language: 'EN',
    country: 'SI',
    currency: 'EUR',
  },
  '/en-sk': {
    label: 'Slovakia (EUR €)',
    language: 'EN',
    country: 'SK',
    currency: 'EUR',
  },
  '/en-sm': {
    label: 'San Marino (EUR €)',
    language: 'EN',
    country: 'SM',
    currency: 'EUR',
  },
  '/en-th': {
    label: 'Thailand (THB ฿)',
    language: 'EN',
    country: 'TH',
    currency: 'THB',
  },
  '/en-va': {
    label: 'Vatican City (EUR €)',
    language: 'EN',
    country: 'VA',
    currency: 'EUR',
  },
  '/en-vn': {
    label: 'Vietnam (VND ₫)',
    language: 'EN',
    country: 'VN',
    currency: 'VND',
  },
  '/en-xk': {

```

--------------------------------

### Custom Color Formats for CSS Variables

Source: https://nghiaxchis.gitbook.io/ciseco-hydrogen-shopifys-headless-theme/cisecos-features/custom-color-fonts

This SCSS code demonstrates how to set CSS variables for theme colors using different color formats: space-separated RGB, HSL, and legacy RGBA. This allows for flexible color definition based on preference or existing color formats. These variables are defined within the :root scope.

```scss
  :root {
    /* For rgb(255 115 179 / <alpha-value>) */
    --color-primary-50: 255 115 179;

    /* For hsl(198deg 93% 60% / <alpha-value>) */
    --color-primary-50: 198deg 93% 60%;

    /* For rgba(255, 115, 179, <alpha-value>) */
    --color-primary-50: 255, 115, 179;
  }
```

--------------------------------

### Define Theme Colors with CSS Variables

Source: https://nghiaxchis.gitbook.io/ciseco-hydrogen-shopifys-headless-theme/cisecos-features/custom-color-fonts

This CSS code defines three main theme colors (primary, secondary, and neutral) using CSS variables. These variables follow a naming convention similar to Tailwind CSS and are intended to be updated to customize the site's overall look and feel. The values are provided in an RGB format.

```css
:root {

  /* For rgb(240 249 255) */
  --c-primary-50: 240, 249, 255;
  --c-primary-100: 224, 242, 254;
  ... 
  --c-primary-900: 12, 74, 110;

  --c-secondary-50: 240, 253, 244;
  ... 
  --c-secondary-900: 20, 83, 45;

  --c-neutral-50: 249, 250, 251;
  ... 
  --c-neutral-900: 17, 24, 39;
}
```

--------------------------------

### Add Custom Font with @font-face Rule

Source: https://nghiaxchis.gitbook.io/ciseco-hydrogen-shopifys-headless-theme/cisecos-features/custom-color-fonts

This CSS code snippet shows how to define a custom font using the @font-face rule and then apply it to the theme's display and body fonts via CSS variables. First, the @font-face rule imports the font file and assigns it a family name and weight. Then, the CSS variables are updated to use this new font.

```css
@font-face {
  font-family: Your_Font;
  font-weight: 600;
  src: url('./fonts/Your_Font/Your_xxxx-SemiBold.ttf');
}

:root {
  --font-display: Your_Font;
  --font-body: Your_Font;
}
```

--------------------------------

### Define Theme Fonts with CSS Variables

Source: https://nghiaxchis.gitbook.io/ciseco-hydrogen-shopifys-headless-theme/cisecos-features/custom-color-fonts

This CSS code sets the primary display and body fonts for the theme using CSS variables. By changing the values of `--font-display` and `--font-body`, you can alter the typography used for headings and body text across the site. The default font specified is 'Poppins'.

```css
:root {
  --font-display: Poppins;
  --font-body: Poppins;
}
```
Tokens:
Raw