Skip to content

Commit

Permalink
React: update Gatsby and Next.js guides (#6710) (#6712)
Browse files Browse the repository at this point in the history
  • Loading branch information
@vladaskorohodova
vladaskorohodova authored Oct 14, 2024
1 parent f5215f2 commit 6bfc63a
Show file tree
Hide file tree
Showing 2 changed files with 60 additions and 54 deletions.
64 changes: 33 additions & 31 deletions ...treme application with Gatsby/10 Create a DevExtreme application with Gatsby.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,12 @@
Gatsby is a prominent member of the latest wave of static website generators. It is an opinionated library with a deep pool of capabilities that include optional server-side rendering and GraphQL support.
---
title: DevExtreme React - Create a DevExtreme-powered Website/Application with Gatsby
---

DevExtreme's powerful client-side components complement Gatsby well, which makes this combo appealing for web developers. This article explains how to use the two products together.
Gatsby is a market-leading static website generator. It is an opinionated library with numerous built-in capabilities including optional server-side rendering and GraphQL support.

## 1. Create an empty Gatsby website
This help topic details the use of DevExtreme UI components alongside the Gatsby framework.

## 1. Create an Empty Gatsby Website

Install the `gatsby-cli` npm package. This command line tool generates, builds, and deploys Gatsby websites.

Expand All @@ -12,7 +16,7 @@ Launch the Gatsby wizard to generate a new website:

gatsby new

Launch the development server to see a live preview of the website:
Launch the development server to display a live preview of the website:

cd my-website
gatsby develop
Expand All @@ -23,7 +27,7 @@ The framework outputs the URL to the command line. Click the link to open it in

![Gatsby website](/images/Gatsby/new-website.png)

Consult [Gatsby documentation](https://www.gatsbyjs.com/docs/tutorial/getting-started/part-1/#create-a-gatsby-site) for an in-depth walkthrough of the process.
For an in-depth Gatsby walkthrough, refer to the following external webpage: [Part 1: Create and Deploy Your First Gatsby Site | Gatsby (gatsbyjs.com)](https://www.gatsbyjs.com/docs/tutorial/getting-started/part-1/#create-a-gatsby-site).

## 2. Add Static Content

Expand Down Expand Up @@ -54,34 +58,34 @@ Gatsby uses React to render content. Edit the `src/pages/index.tsx` file to chan
)
};

Save your changes. Your page should look like this:
Save your changes. Your page should be rendered as follows:

![Static content](/images/Gatsby/lipsum-page.png)

## 3. (Optional) Use Server-Side Rendering with Netlify

Gatsby has a tight integration with Netlify — a cloud platform for web applications. Platforms like Netlify allow you to render Gatsby pages on the server.
Gatsby integrates with Netlify — a cloud platform for web applications. Platforms like Netlify allow you to render Gatsby pages on the server.

You can connect a GitHub repository with a Gatsby website to your Netlify account. Netlify will deploy the website, and update it every time you push changes to your repository.
You can connect a GitHub repository with a Gatsby website to your Netlify account. Netlify will deploy the website and update it each time you push changes to your repository.

1. Create a new GitHub repository.
2. Push the contents of your local Gatsby repo to GitHub.
3. Sign up for Netlify (you can use your GitHub account).
4. Import your GitHub repository from Netlify and deploy your website (see [this tutorial](https://docs.netlify.com/welcome/add-new-site/)).

Let's conduct a little experiment to check whether server-side rendering works. Disable JavaScript in your browser and reload the page.
Let's now check whether server-side rendering works as expected. Disable JavaScript in your browser and reload the page.

If you run a development server, Gatsby renders its content on the client. When you disable JavaScript, the page goes blank:
If using a development server, Gatsby renders its content on the client. When you disable JavaScript, the page is blank:

![The development server displays a blank page when you disable JavaScript](/images/Gatsby/blank-page.png)

If you deploy your website on Netlify, Gatsby renders your content on the server, and you can see the content:
If using Netlify, Gatsby renders your content on the server (you can view content):

![Gatsby renders content on the server](/images/Gatsby/ssr-example.png)

## 4. Add DevExtreme to the application
## 4. Add DevExtreme to the Website

We're ready to add a [DevExtreme DataGrid](/api-reference/10%20UI%20Components/dxDataGrid '/Documentation/ApiReference/UI_Components/dxDataGrid/') to our application. First, add DevExtreme to your project dependencies:
We're ready to add the [DevExtreme DataGrid](/api-reference/10%20UI%20Components/dxDataGrid '/Documentation/ApiReference/UI_Components/dxDataGrid/') to our application. First, add DevExtreme to your project dependencies:

<!--tab: package.json-->
"dependencies": {
Expand All @@ -91,7 +95,7 @@ We're ready to add a [DevExtreme DataGrid](/api-reference/10%20UI%20Components/d
<...>
}

Run `npm install` to install new dependencies. When the installation is complete, add a DataGrid component to the index page:
Run `npm install` to install new dependencies. When installation is complete, add a DataGrid component to the index page:

<!--tab: index.tsx -->
import * as React from "react";
Expand Down Expand Up @@ -189,39 +193,37 @@ Run `npm install` to install new dependencies. When the installation is complete
)
};

Refresh the page to view the result:
Refresh the page to view results:

![A DevExtreme grid without a theme](/images/Gatsby/grid-without-a-theme.png)

[note] DevExtreme components are *always* rendered on the cilent. If you disable JavaScript and refresh your Netlify deployment, you won't see the DevExtreme grid.

## 5. Apply a DevExtreme theme
[note] DevExtreme components are *always* rendered on the client. If you disable JavaScript and refresh your Netlify deployment, you will not see the DevExtreme Grid.

The application displays a DevExtreme grid, but does not style it appropriately. If you want the grid to look good, style it with a [DevExtreme theme](/concepts/60%20Themes%20and%20Styles/05%20Predefined%20Themes/00%20Predefined%20Themes.md '/Documentation/Guide/Themes_and_Styles/Predefined_Themes/').
## 5. Apply a DevExtreme Theme

You can apply a DevExtreme theme to the grid in one of two ways:
As you can see in the screenshot above, the website displays the DevExtreme Grid but does not style it appropriately. To style our data grid using [DevExtreme theme](/concepts/60%20Themes%20and%20Styles/05%20Predefined%20Themes/00%20Predefined%20Themes.md '/Documentation/Guide/Themes_and_Styles/Predefined_Themes/') you can:

* Apply a DevExtreme theme to the entire application. This approach works best when your website includes DevExtreme components on most pages. Otherwise, it may unnecessarily increase the load time of your application.
* Apply a DevExtreme theme on a per-page basis. This approach works best if only a few pages of your website include DevExtreme components.
* Apply a DevExtreme Theme to the entire application. This approach works best when your app includes DevExtreme UI components across most pages (by using this approach, the overall load time of your application may increase).
* Apply a DevExtreme Theme on a per-page basis. This approach works best if DevExtreme UI components are used sparingly throughout the website (on a few pages).

### Apply a theme to the entire website
### Apply a Theme to the Entire Website

If you want to apply a single DevExtreme theme to your entire website, add a file named `gatsby-browser.js` to the root folder of your project.
To apply a single DevExtreme theme to your website, add a file named `gatsby-browser.js` to the root folder of your project.

Add the following `import` statement to the file:

<!--tab: gatsby-browser.js-->
import 'devextreme/dist/css/dx.light.css';

This statement applies the `light` theme to the DevExtreme grid.
This statement applies the `light` theme to the DevExtreme DataGrid.

Restart the Gatsby server to compile new assets. The grid should look like this:
Restart the Gatsby server to compile new assets. The DevExtreme Data Grid will be rendered as follows:

![A DevExtreme grid with a theme](/images/Gatsby/grid-with-a-theme.png)

### Apply the theme to a specific page
### Apply a Theme to a Specific Page

If you want to apply a DevExtreme theme to a specific page, do not import this theme globally. Instead, add a `link` to the `Head` of the target page:
To apply a DevExtreme theme to a specific page, do not import the theme globally. Instead, add a `link` to the `Head` of the target page:

export const Head: HeadFC = () =>
{
Expand All @@ -233,14 +235,14 @@ If you want to apply a DevExtreme theme to a specific page, do not import this t
)
};

This link downloads the `light` theme from the [DevExpress CDN](/concepts/Common/Distribution%20Channels/05%20CDN '/Documentation/Guide/Common/Distribution_Channels/CDN/') and applies it to the page. If you need to insert this code into multiple pages, save it as a separate component.
This link downloads the DevExtreme `light` theme from the [DevExpress CDN](/concepts/Common/Distribution%20Channels/05%20CDN '/Documentation/Guide/Common/Distribution_Channels/CDN/') and applies it to the page. If you need to insert this code into multiple pages, save it as a separate component.

Modify the name of the stylesheet to apply [a different theme](/concepts/60%20Themes%20and%20Styles/05%20Predefined%20Themes/00%20Predefined%20Themes.md '/Documentation/Guide/Themes_and_Styles/Predefined_Themes/'). Modify the name of the subfolder (`23.1.3`) to apply a theme that is compatible with a different version of DevExtreme.

## 6. Next Steps

DevExtreme components are powerful, easy to use, and fully compatible with Gatsby. View our [application templates](https://js.devexpress.com/React/Templates/) and [demos](https://js.devexpress.com/Demos/WidgetsGallery/) to discover the full capabilities of DevExtreme components.
DevExtreme UI components are intuitive, easy to use, and fully compatible with Gatsby. Review our [application templates](https://js.devexpress.com/React/Templates/) and [demos](https://js.devexpress.com/Demos/WidgetsGallery/) to explore the capabilities of DevExtreme UI components at your own pace.

Read the [Gatsby documentation](https://www.gatsbyjs.com/docs) for more information the Gatsby framework.
For additional information on the Gatsby framework, refer to the following external webpage: [Welcome to the Gatsby Way of Building | Gatsby (gatsbyjs.com)](https://www.gatsbyjs.com/docs).

[tags] react
50 changes: 27 additions & 23 deletions ...eme application with Next.js/20 Create a DevExtreme application with Next.js.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,14 @@
Next.js is a React-based web development framework. It can both generate static websites and serve dynamic content. The creators of React endorse Next.js because Next is easy to use, feature-rich, and compatible with modern web development patterns, such as server-side page rendering.
---
title: DevExtreme React - Create a DevExtreme-powered Website/Application with Next.js
---

This article explains how to create a simple Next.js application, and populate it with DevExtreme components.
Next.js is a React-based web development framework. It can generate static websites and serve dynamic content. The creators of React endorse Next.js because Next is easy to use, feature-rich, and compatible with modern web development patterns (such as server-side page rendering).

## 1. Create a new project
This help topic details the use of DevExtreme UI components alongside the Next.js framework.

> Read the [official Next.js documentation](https://nextjs.org/docs/getting-started/installation) for an in-depth overview of the installation process.
## 1. Create a New Project

Consult the following external webpage if you are new to Next.js: [Getting Started: Installation | Next.js (nextjs.org)](https://nextjs.org/docs/getting-started/installation).

The `create-next-app` wizard allows you to bootstrap a Next.js web app in a matter of minutes.

Expand All @@ -16,7 +20,7 @@ Run the following command to launch the wizard:

npx create-next-app@latest

Answer the wizard's prompts to configure your new app. For the purposes of this tutorial, we enabled the following options:
Answer the wizard's prompts to configure your new app. For this tutorial, we enabled the following options:

* TypeScript support
* ESLint support
Expand All @@ -37,11 +41,11 @@ The server outputs the preview URL to the console. The default URL is `http://lo

Proceed to the next step when you get the server up and running.

## 2. Add static content to the front page
## 2. Add Static Content to the Front Page

During the set-up process we selected the "Store source code in the `src/` directory" option. As such, the `src/app/page.tsx` file stores the source of your application's front page.
During the set-up process we selected the "Store source code in the `src/` directory" option. As such, the `src/app/page.tsx` file stores the source for your app’s front page.

Let's replace the content of the page with a simple heading and a paragraph:
Let's replace page content with a simple heading and a paragraph:

<!--tab: page.tsx-->
export default function Home() {
Expand All @@ -62,7 +66,7 @@ Let's replace the content of the page with a simple heading and a paragraph:

The `page.tsx` file no longer references the `page.module.css` file. Delete the CSS file from disk.

The `globals.css` file contains global styles, including the setting that configures the default background color. It is **unsafe** to remove this file. Delete the following CSS code to make the background plain:
The `globals.css` file contains global styles, including the setting used to configure the default background color. It is **unsafe** to remove this file. Delete the following CSS code to apply a plain background:

<!--tab: globals.css-->
body {
Expand All @@ -77,41 +81,41 @@ The `globals.css` file contains global styles, including the setting that config

### View the server-rendered page

The page should look like this:
Your page should appear as follows:

![Modified page](/images/NextJS/modified-page.png)

Next.js rendered this content on the server. This means that you can view it in a browser that prohibits the execution of client-side JavaScript. Try it yourself --- go to your browser settings, disable JavaScript, and refresh the page.
Next.js rendered this content on the server. This means you can view the page in a browser that prohibits execution of client-side JavaScript. Try it yourself - go to your browser settings, disable JavaScript, and refresh the page.

![Disable JavaScript](/images/NextJS/disable-javascript.png)

The page should not change.

![Modified page](/images/NextJS/ssr-example.png)

Turn JavaScript back on to continue the tutorial.
Activate JavaScript to continue the tutorial.

## 3. Add a DevExtreme DataGrid
## 3. Add a DevExtreme Grid

### Install dependencies
### Install Dependencies

Run the following command to install the necessary DevExtreme packages and save them to your package dependency list:

npm install [email protected] [email protected] --save-exact

### Set up the necessary imports
### Set up the Necessary Imports

Open the `page.tsx` file. Add the following `import` statements at the beginning:

<!--tab: page.tsx-->
import DataGrid from 'devextreme-react/data-grid';
import 'devextreme/dist/css/dx.light.css';

The first `import` allows you to use the DataGrid component. The second applies the default "Light" theme to DevExtreme components.
The first `import` allows you to use the DataGrid component. The second applies the default "Light" theme to DevExtreme UI components.

### Set up a Data Source

The DataGrid component requires a data source. For the purpose of this tutorial, we'll use data from the publicly available [Cat Facts API](https://catfact.ninja). Add the following asynchronous code to the `page.tsx` file:
Our DataGrid requires a data source. For the purpose of this tutorial, we'll use data from the publicly available [Cat Facts API](https://catfact.ninja). Add the following asynchronous code to the `page.tsx` file:

<!--tab: page.tsx-->
const getCatFacts = async (): Promise<any[]> => {
Expand All @@ -125,7 +129,7 @@ The DataGrid component requires a data source. For the purpose of this tutorial,

### Configure the DataGrid

[note] The Next.js Router imposes additional limitations on DevExtreme components. Components without the ["use client" directive](https://nextjs.org/docs/app/building-your-application/rendering/client-components#using-client-components-in-nextjs) only accept props of primitive data types. Include this directive to use custom DevExtreme data types such as `ArrayStore` and `ODataStore`.
[note] The Next.js Router imposes additional limitations on DevExtreme UI components. Components without the ["use client" directive](https://nextjs.org/docs/app/building-your-application/rendering/client-components#using-client-components-in-nextjs) only accept props of primitive data types. Include this directive to use custom DevExtreme data types such as `ArrayStore` and `ODataStore`.

Create a new React component with the name `DemoGrid`. Use this component to define and configure a new instance of the DevExtreme DataGrid:

Expand All @@ -144,7 +148,7 @@ Create a new React component with the name `DemoGrid`. Use this component to def
);
}

### Insert the DataGrid component into the page
### Insert the DataGrid Into the Page

Modify the Home function to include the `DemoGrid` component we created in the previous step:

Expand All @@ -164,13 +168,13 @@ Modify the Home function to include the `DemoGrid` component we created in the p
)
}

### View the client-side rendered grid
### View the Client-side Rendered Grid

If your server runs in development mode, refresh the browser window. If your server runs in production mode, build the application, and restart the server:

npm run build; npm run start

The page should display an interactive grid with data from the Cat Facts API.
The page should now display an interactive grid with data from the Cat Facts API.

![Client-side grid](/images/NextJS/client-side-grid.png)

Expand All @@ -180,8 +184,8 @@ DevExtreme renders the DataGrid on the client, even if the rest of the page is r

## 4. Next Steps

DevExtreme components are powerful, easy to use, and fully compatible with Next.js. View our [application templates](https://js.devexpress.com/React/Templates/) and [demos](https://js.devexpress.com/Demos/WidgetsGallery/) to discover the full capabilities of DevExtreme components.
DevExtreme UI components are intuitive, easy to use, and fully compatible with Next.js. Review our [application templates](https://js.devexpress.com/React/Templates/) and [demos](https://js.devexpress.com/Demos/WidgetsGallery/) to explore the capabilities of DevExtreme UI components at your own pace.

Read the [Next.js documentation](https://nextjs.org/docs) for more information on the Next.js framework.
For additional information on the Next.js framework, refer to the following external webpage: [Introduction | Next.js (nextjs.org)](https://nextjs.org/docs).

[tags] react

0 comments on commit 6bfc63a

Please sign in to comment.